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About This Book 


The IBM Operating System/2 Procedures Language 2/REXX User's Guide (referred 
to as User's Guide in the rest of this book) describes the programming language 
known as REXX. REXX is an integral part of IBM OS/2* 2.0. This guide describes 
how to write programs using REXX. 


Before You Begin 


Before reading this book, it is important that you consider the following items: 


What You Need 
This is what you need to get started: 


¢ Your computer with the OS/2 program installed. 


e A text-editing or word-processing program such as the system editor supplied 
with the OS/2 program. Whatever editor you use must be able to create 
straight-ASCTI files (nearly all such programs can). 


¢ OS/2 2.0 Procedures Language 2/REXX Reference. 


It is also useful, though not essential, to have a printer so you can print your 
programs. 


What You Need to Know 


To use this book, you should know: 
¢ What a file is and how to create a text file 
¢ How to use an editor or word processor 
e¢ The basic OS/2 commands for manipulating files, such as COPY, DELETE, 
DIR, and so on. 
If you have little or no experience with the OS/2 program or with personal 
computers, you may want to read the following publications: 


¢ OS/2 2.0 Overview 
© OS/2 2.0 Installation Guide 


Who Should Read This Guide 


Both inexperienced and experienced computer users should read this guide to learn 
about REXX. The guide shows how REXX is a useful programming language for 
both the experienced programmer and the user new to programming. 
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How This Guide Is Structured 


Each chapter, except chapter 1, is divided into two parts: 


¢ The first part of each chapter, Basics, is a tutorial guide to the most frequently 
used features of REXX. “Basics” in each chapter builds on the preceding 
chapters and prepares you for those that follow. 


¢ The second part of each chapter, Advanced Topics, discusses more advanced 
information about REXX and includes descriptions and examples of the more 
specialized features of REXX. 
Each chapter of this Guide concentrates on a single topic. 


¢ Chapter 1, “Introduction to REXX,” is a brief introduction to programming 
and REXX. 


¢ Chapter 2, “How REXX Works,” describes how the program works. 

¢ Chapter 3, “Variables,” tells about handling data in terms of symbols. 

¢ Chapter 4, “Expressions,” shows how REXX computes information. 

¢ Chapter 5, “Commands,” describes using REXX with OS/2 and other programs. 
¢ Chapter 6, “Program Control,” tells about refining and automating programs. 

¢ Chapter 7, “Program Structure,” tells about running programs within programs. 
¢ Chapter 8, “Parsing,” tells about reading and analyzing data. 

e Chapter 9, “Arithmetic,” shows how REXX calculates numbers. 

¢ Chapter 10, “Input and Output,” describes using REXX with outside data. 

¢ Chapter 11, “Program Style,” describes how to plan and correct programs. 


e Chapter 12, “Using REXX with Applications,” describes how to use certain 
REXX features to get the most from the operating system. 
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Chapter 1. Introduction to REXX 


The REstructured eXtended eXecutor language, or REXX, is a versatile, easy to use 


structured programming language that is an integral part of the OS/2* program. Its 
simplicity makes it a good first language for beginners. For more experienced users 
and computer professionals, REXX offers powerful functions, extensive 
mathematical capabilities, and the ability to issue commands to multiple 
environments. 


Features of REXX 


Ease of Use 


Free Format 


interpreted 


Built-in Functions 


The following REXX features contribute to its versatility and function. 


REXxX is easy to learn and use because many instructions are meaningful English 
words. Unlike some programming languages that use abbreviations, REXX 
instructions are common words such as SAY, PULL, IF...THEN...ELSE, 
DO...END, and EXIT. 


REXX has few rules about format. A single instruction can span many lines or 
multiple instructions can be entered on a single line. Instructions do not have to 
begin in a particular column and can be typed in uppercase, lowercase, or mixed 
case. Spaces can be skipped in a line or entire lines can be skipped. There is no line 
numbering. 


REXX is an interpreted language. When a REXX program runs, its language 
processor reads each statement from the source file and runs it, one statement at a 
time. Languages that are not interpreted must be compiled into machine language 
(in separate files) before they can be run. 


REXX has built-in functions that perform various processing, searching, and 
comparison operations for both text and numbers. Other built-in functions provide 
formatting capabilities and arithmetic calculations. 


Typeless Variables 


REXX regards all data as character strings. This means that there is no need to 
predefine variables or variable arrays as strings or as numbers. REXX performs 
arithmetic operations on any string that represents a valid number, including those 
in exponential formats. 
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Parsing Capabilities 
REXX< includes capabilities for manipulating character strings. This allows 
programs to read and separate characters, numbers, and mixed input. 


Debugging 
REXX displays messages with meaningful explanations when a REXX program 
encounters an error. In addition, the TRACE instruction provides a powerful 
debugging tool. 


REXX and the OS/2 Program 


The most vital role REXX plays is as a procedural language for the OS/2 program. 
A REXX program can serve as a script for the OS/2 program to follow. By using 

REXX, long, complex, or repetitious tasks can be reduced to a single command or 
program that can be run from Presentation Manager. 


REXX< is a built-in feature of the OS/2 program, so programs are run directly from 
an windowed or full-screen command prompt. There is no installation process or 
separate environment. Anywhere that an OS/2 command or batch file can be used, 
a REXX program can be run. Any REXX program can call OS/2 commands. 


About REXX and SAA 


REXX< is one of the programming languages included in the IBM Systems 
Application Architecture* (SAA*). SAA is a framework of standards and definitions 
intended to promote consistency among different IBM products. Programs written 
in REXX according to SAA specifications are portable to all other SAA 
environments. For example, a REXX program written for OS/2 environment can be 
run in a CMS or TSO/E environment, if the program does not use OS/2-specific 
features. 


To learn more about using REXX in SAA environments, see the Common 
Programming Interface Procedures Language Reference, SC24-5549. 


About Programming 


A program is a list of instructions that have a basic sequence. Some instructions 
indicate actions and some instructions specify the number and sequence of these 
actions. There are also instructions to tell you how to execute other instructions. 
Those that specify repetitious actions are iterative. Those that indicate when an 
action should begin or end are conditional. 


You may think of programming as a skill practiced only by computer experts, but 
that is not true. You do not need to know how a computer works to write a 
program. Anyone can write a program, and almost everyone who uses a computer 
eventually needs to do so. With a little programming knowledge, you can reduce a 
long or repetitious series of commands into a single command. You can also 
customize OS/2 programs and other programs to work in a way that will best suit 
your needs. Programming helps you make the computer work faster or better. That 
is what REXX was meant for, and this book should make REXX easier to 
understand. 
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If You Have Never Written a Computer Program 
If you are inexperienced at programming, you will find it fairly easy to learn and 
write programs in REXX. Start by reading “Basics” in each chapter. After you 
have read “Basics,” go back and read “Advanced Topics” in each chapter to learn 
more about specific topics. 


If You Are Already Familiar With Another Language 
If you are an experienced programmer, reading “Basics” in each chapter gives you 
an overview of the REXX language. Or, you may prefer to read about individual 
topics, one at a time. Here are some areas you may want to investigate: 


If you now use OS/2 CMD files to automate your work, you will find that 
REXX gives you more flexibility in controlling program flow and in handling 
parameters. Refer to Chapter 5, “Commands,” which discusses how REXX 
works with OS/2 commands. 


If you are skilled in BASIC, you may want to note these ways that REXX 
differs from BASIC: 


— There is no line numbering. 

~ There are no GOSUB or GOTO statements. Use CALL and SIGNAL 
instead (see “Subroutines” on page 7-1). 

~ REXX variables have no data type. 

— There are no DIM arrays. Use compound variables instead (see “Using 
Compound Symbols” on page 3-8). 


If you are familiar with development languages, such as C and Pascal, you will 
find REXX somewhat similar. Again, the main difference is that a REXX 
program is interpreted; that is, the source code of the program is processed line 
by line. There is no compiling process. 


Refer to Chapter 5, “Commands,” for examples of command-passing and 
Chapter 10, “Input and Output,” for examples of file and queue processing. 


Exercises and Examples 
As with other programming languages, you do not learn REXX by reading about it. 
Exercises and examples are included to help you learn REXX by using it. To get the 
most out of this book: 


Test yourself with the exercises as you read. 


Examine the examples and sample programs in the text. Type them exactly as 
they are shown. 


Try your own variations of each program. See if you can find a different or 
better way to do what the sample program does. 


Note: When your REXX program issues an OS/2 command, REXX passes the 
command to the OS/2 command handler for processing. This processing includes 
displaying the command on the screen (echoing). 


For the sake of simplification, the examples in this book do not include echoing of 
the commands. 


Chapter 1. Introduction to REXX 1-3 


The REXX Reference 
The REXX Reference contains a more complete description of how to use the REXX 
language. You should have a copy of this book, so you can look up any instruction 
or function not completely defined here. Think of the REXX Reference as a 
dictionary for REXX and this User's Guide as a book of directions and ideas. 


The Procedures Language/2REXX is available online. It contains information on 
REXX features, functions, and instructions. 
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Chapter 2. How REXX Works 


A REXX program is a list of instructions for your computer. The program is simply 
a text file that you create with a text-editing or word-processing program. 

Sometimes a computer runs a program with no guidance. Other times it may need 
additional information from the user to do its work. One way that a computer 
communicates with the user is to ask questions and then compute results based on 
the responses. The programmer (you) can include instructions that let the computer 
converse with the user. 


Basics 
In this chapter: 


Basics 


> A computer conversation—creating and running your first REXX program 
and how REXX interprets it 


> What goes into a program—elements in the grammar of REXX. 
> Syntax errors—how to read REXX messages. 


A Computer Conversation 
Figure 2-1 shows a sample REXX program. It asks users to type their names. Then 
the program greets the user by that name. For example, if the user types Jean, the 
program displays Hello JEAN on the screen. If the user does not type anything, the 
program displays Hello stranger! on the screen. 


/* A conversation */ 
say "Hello! What is your name?" 


pull who 
if who = "" then say "Hello stranger!" 
else say "Hello" who 


Figure 2-1. HELLO.CMD 


This sample program consists of five statements called clauses. The various pieces of 
this program are: 


| eee ens 5 The first clause is a comment explaining what the 
program is about. All REXX programs must start with 
a comment beginning in column 1. Except for this, all 
other comments are ignored. 


say The second clause is the keyword instruction say, which 
displays text on the screen. 


"Hello!..." Anything in quotes after say is displayed on the screen 
exactly as it was typed. This is called a literal string. 


pull The third clause is the keyword instruction pull, which 
reads and stores the response typed by the user of the 
program. 
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who : This is a variable: a name given to the place in memory 
where the user’s response is stored. 


if The fourth clause is the keyword instruction if, which 
tests for a given condition. 

who = "" The condition to be tested: whether the variable who is 
empty. 

then Tells the program to process the instruction that follows, 
if the tested condition is true. 

say "Hello stranger!" Displays Hello stranger! on the screen if the condition 
is true. 

else This final clause gives an alternative direction: process 
the instruction that follows, if the tested condition is not 
true. 

say "Hello" who Displays Hello, followed by whatever data is stored in 


who, if the tested condition is not true. 
Creating Your First Program 
Follow these steps to create your first program by: 


1. Using a word processor or editor to create a text file named HELLO.CMD. Be 
sure to make it a straight-ASCII or nondocument file, without special formatting 
characters. 


2. Typing the HELLO.CMD program exactly as shown in Figure 2-1 on page 2-1. 
Be sure that the first line begins with /* and ends with */. 


3. Saving the file and then returning to Presentation Manager. 
Running the Program 
Follow these steps to run the sample program from the OS/2 command prompt by: 


1. Typing the file name of the program. In this example, type hello at the OS/2 
prompt and press the Enter key. 


2. Typing your name and pressing the Enter key. If your name is Fred, Hello 
FRED is displayed on the screen. 


[C:\] hello 
Hello! What is your name? 


fred 
Hello FRED 


[c:\] 


When you run this program: 
1. The SAY instruction displays Hello! What is your name? on the screen. 
2. You type fred on the command line and press the Enter key. 


3. The PULL instruction puts FRED into the variable (the place in memory) called 
who. 
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Problems 


4. The IF instruction tests, is who equal to nothing? 


who = ™" 


To find out, REXX substitutes the stored value for the variable name. Now the 
question is, is FRED equal to nothing? 
W FRED" =- Hn 


5. Not true. The SAY instruction after then is not processed. Instead, REXX 
processes the SAY instruction after else. 


6. The SAY instruction displays "Hello" who, which is evaluated as Hello FRED on 
the screen. 


The following is displayed on the screen, if you press the Enter key without typing a 
response. 


[C:\] hello 
Hello! What is your name? 


Hello stranger 


[c:\] 


When you run this program: 


1. The PULL instruction puts nothing ("") into the variable (the place in memory) 
called who. 


2. The IF instruction tests is who equal to nothing? 
who = "" 


When the stored value of who is substituted, this is: 


3. This time, it is true. The SAY instruction after then is processed, and the SAY 
instruction after else is not. 


Did you get your version of HELLO.CMD to run? If not, check that you have 
correctly typed it in. Also, be sure that you used the nondocument mode of your 
text editor to create the program file. 


The most common error is forgetting the comment on the first line. Be sure that the 
first line begins with the /* and ends with the */ characters. If you mistype or omit 
these characters, you get a message on the screen from REXX that looks something 

like this. 


[C:\] hello 
0 +++; 


REXO006: Error 6 running C:\HELLO.CMD, line 0: Unmatched "/*" or quote 
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This means that REXX found the beginning /* but not the ending */ of the 
comment. Edit your HELLO.CMD program file to match the sample in Figure 2-1 
on page 2-1. 


If you do not start the first line with /*, you get a message like this. 


SYS1041: The name specified is not recognized as an 
internal or external command, operable program or batch file. 


This means that the operating system did not recognize HELLO.CMD as a REXX 
program. (See “First-line Comments” in the following text.) 


If you get another error, refer to “Fixing Syntax Errors” on page 2-6. 


Stopping a Program 
If you need to stop a program, press the Control (Ctrl)+Break keys. That is, press 
and hold down the Ctrl key and then press the Break key once. REXX stops 
running the program and returns to the OS/2 command prompt. 


What Goes into a Program 
To explain what happens when you run a REXX program, a number of terms have 
been introduced. There will be more; so before continuing, here are definitions of 
the terms used so far. 


Comments 
When you write a program, you will want to read it later (for example, before 
improving it). Other users of your program will also want to read it to know what 
the program is for, what kind of input it can handle, what kind of output it 
produces, and so forth. You may also want to write remarks about individual 
instructions. All these things, words that are to be read by people but not 
interpreted by REXX, are called comments. 


To indicate comments, use /* to mark the start of a comment and */ to mark the 
end of a comment. 


The /* causes REXX to stop interpreting the program. Interpreting starts again 
only after a */ is found, which may be a few words or several lines later. For 
example: 


/* This is a comment. */ 
say ... /* This is a comment on the same line as the instruction */ 


/* Comments may 
occupy more 
than one line. */ 


First-line Comments: The first line of a REXX program must start with a 
comment. The OS/2 program can be programmed with its built-in Batch Facility 
and in REXX. Both Batch Facility and REXX programs can use the file name 
extension CMD. Each type requires its own special processing, so the OS/2 program 
checks the first line of the program. If it finds a REXX-style comment, the program 
is processed as REXX. Therefore, to recognize that your program is written in 
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REXX, the first line of the file must be or begin a comment. For example: 
/* this is a REXX program. */ 


Also, the first-line comment must begin in column 1. It is sufficient to use /* */, 
but a better use for the space is to give a brief description of your program. You 
can also do it this way. 

[REPEECTRE CRS RERAREAARERSN SESS TAESES ES 

* HELLO.CMD written by J. Smith * 


* June 30, 1989 * 


* A program to greet a user by name. * 
REREERERAEREEEREREE RARER EERE NE ER REGED | 


Keyword Instructions 


Literal Strings 


Words such as SAY, PULL, and IF are part of the REXX language called 
instructions. The words themselves are referred to as keywords. You will notice that 
they are usually verbs. They are the directions that tell REXX what to do with 
information at a certain point in the program. 


SAY (display on screen) hello. 
PULL (accept and store) information from the user. 
IF (test) this situation is true, then perform this action. 


When you list these instructions in the order you want REXX to execute them, you 
have created a program. 


Clauses: A REXX program is made up of clauses; that is, complete instructions, 
including the information it works on and any options that may be used. REXX 
reads each clause and processes it before going on to the next. That is why REXX is 
an interpreted language. 


In the previous sample program, each line of text corresponds to a single clause. 
REXX allows exceptions to this (see “More about Clauses” on page 2-10). The 
examples and sample programs in this book follow the convention of one clause to a 
line, except where noted. 


When REXX finds a quote (either " or '), it stops processing and looks ahead for 
the matching quote. The string of characters inside the matching quotes is used as it 
is and is called a literal string. Examples of literal strings are: 


‘Hello’ 
"Final result:" 


If you need to use quotation marks within a literal string, use quotation marks of the 
other type to delimit the string. For example: 


"Don't panic" 
‘He said, "Bother"' 


There is another way. Within a literal string, a pair of quotes (the same type that 
delimits the string) is interpreted as one of that type. For example: 


'Don''t panic' (same as "Don't panic") 
“He said, ""Bother""" (same as 'He said, "Bother"') 
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Variables 


Uppercase Translation: When a clause is processed, any letters that are not in 
quotes are translated to uppercase. For example, the letters a, b, c, ... Zz are 
changed to A, B, C, ... Z. This translation applies only to clauses written in 
English. 


REXX also ignores some of the spaces that you may have written into your 
program, keeping only one space between words. Figure 2-2 shows an example 
using quotes to get more than one space between words. 


/* Example: cases and spaces */ 
say Hello! What is your name? 


say "Hello! What is your name?" 


say Hello!" "stranger! 


Figure 2-2. HELLO2.CMD 


The following is displayed on the screen, when you run the HELLO2 program. 


[C:\] hello2 
HELLO! WHAT IS YOUR NAME? 


Hello! What is your name?" 
HELLO! STRANGER! 
[C:\] 


Note: In the HELLO.CMD sample program, the user’s input fred was changed to 
FRED. That translation is not the process described here, but is a feature of the 
PULL instruction. The PULL instruction always converts the input to uppercase, 
which allows the user to type any combination of uppercase and lowercase letters. 


When you need to work with changeable information (such as the user’s name in 
HELLO.CMD), you can reserve a place in memory to store it. That place is called 
a variable. 


When REXX processes a clause containing a variable, it substitutes the stored data 
for the variable. That is how the stored entry FRED took the place of the variable 
name who in the HELLO.CMD program. 


Refer to Chapter 3, “Variables,” for more information on variables. 


Fixing Syntax Errors 


The rules governing the arrangement of words and punctuation marks in a language 
are called syntax. The actions described are part of the syntax for the REXX 
language. If REXX encounters something that does not make sense according to its 
syntax, it stops running your program, displays the incorrect instruction line and an 
error message saying what is wrong, and returns to the OS/2 program. 
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Figure 2-3 shows the HELLO.CMD program with a syntax error. The */ is missing 
at the end of the second comment. 


/* A conversation */ 
say "Hello! What is your name?" 


pull who /* Get the answer! 
if who = "" then say "Hello stranger!" 
else say "Hello" who 


Figure 2-3. HELLO.CMD with a syntax error 


The following is displayed on the screen, when you run the program and enter fred. 


[C:\] hello 
Hello! What is your name? 
fred 


REXO9006: Error 6 running C:\HELLO.CMD,line 3: Unmatched "/*" or quote 


[c:\] 


This error message means: 


e REX0Q006: is the REXX error number. If you need more information, type help 
followed by the error number (REX0006) at the command prompt and press the 
Enter key. More information about the error is displayed. You can also find 
error message help in the REXX Reference. 


e The phrase in line 3 means REXX was processing the clause that started on 
line 3 when the error occurred. 


Leaving out a final quotation mark at the end of a literal string causes REXX to 
issue a similar error message. 


Test Yourself 
1. Read the following program and write down what each clause is and what 
REXX will do with it, depending on how the user responds. 


/* Who Am I? game */ 
say "What is my name?" 


pull guess 
if guess = "REXX" then say "You win!" 
else say no but guess "is a good guess." 


Figure 2-4. WHOAMI.CMD 


Create a file called WHOAMI.CMD, type the program shown in Figure 2-4, 
and run it. 


Did everything happen as you expected? If not, read this chapter again and then 
study the explanation below. 
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2. Figure 2-5 shows a program with an error in it. Create a file called 
TROUBLE.CMD, type the program, and run it. 


/* Example: a syntax error */ 


say Unfortunately, there is an error here 


Figure 2-5. TROUBLE.CMD 


Using the error number, find the cause of the error in the REXX Reference. 
Correct the error and run the program again. 


Answers: 


1. The syntax of the WHOAMI.CMD program shown in Figure 2-4 on page 2-7 
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1S: 


/* Who Am I? game */ is a comment describing the program. (The first line 
of a REXX program must start with a comment.) 


say is an instruction that displays, What is my name? 
pull is an instruction that stores the user response in the variable guess 
if is an instruction that tests to see if the user typed REXX. 


Note: Because pull translates the entry to uppercase, you can type it in any 
combination of uppercase and lowercase letters (rexx, Rexx, rExX, and so 
on). 


If guess = REXX, then say displays You win!. 


If the user types something other than REXX, then the clause beginning with 
else is interpreted and say displays the result as follows: 


— no but is a string, but it is not in quotes. Therefore, it is changed to 
uppercase and is displayed as NO BUT. 


— guess is the name of a variable. The user’s response, translated to 
uppercase, is substituted. 


— "is a good guess." is a literal string. It is displayed as is, even though 
guess is also the name of a variable. 


The following is displayed on the screen, if the user guesses correctly. 


[C:\] whoami 
What is my name? 


PeXX 
You win! 


The following is displayed on the screen, if the user guesses incorrectly. 


[C:\] whoami 
What is my name? 


spot 
NO BUT SPOT is a good guess. 


The following is displayed on the screen, if the user presses the Enter key 
without typing a response. 


[C:\] whoami 
What is my name? 


NO BUT is a good guess. 


The variable guess was empty, so the say instruction displayed nothing. Only 
the blank before and after the variable in the program remain. 


That last response does not make much sense. See if you can think of a way to 
fix WHOAMI.CMD so that it does. (Hint: Take another look at 
HELLO.CMD.) 


2. The error number for the program TROUBLE.CMD is 37. The error message 
displays Unexpected "," or ")". 


REXX found a comma where it did not belong. It may not be obvious what to 
do about it. When you get a message like this, refer to the REXX Reference for 
a list of error messages and explanation of their causes. 


The comma has a special meaning when it is used outside of a literal string (see 
“More about Clauses” on page 2-10). Figure 2-6 shows that to use a comma as 
it is intended, it must be enclosed in matching quotes. 


/* Example: a syntax error fixed */ 


say Unfortunately"," there is an error here 


Figure 2-6. TROUBLE2.CMD 


Summary 


This completes “Basics” in this chapter. You have learned that REXX reads a 
literal string. In addition, you have learned how to: 


e Write a program 
e Run a program 
¢ Use the SAY and PULL instructions. 


“Advanced Topics” in this chapter discusses more about the structure of REXX 
programs. 


To continue with “Basics,” go to page 3-1. 
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Advanced Topics 
In this chapter: 


Advanced Topics 


> Kinds of clauses—more about REXX syntax. 


More about Clauses 
Your REXX program is made up of a number of clauses. REXX processes clauses, 
one at a time, reading from left to right. 


Usually, each clause occupies one line of the program, but that is only a convention. 
It is sometimes useful to be able to write more than one clause on a line or to extend 
a clause over many lines. The rules for writing clauses are: 


e If you want to put more than one clause on a line, you must use a semicolon (;) 
to tell REXX where one clause ends and the next begins. 


e If you have a long quoted string that you would like to span several lines, write 
it as several separate strings and concatenate them. Quoted strings cannot span 
more than one line. 


¢ If you want a clause to span more than one line, you must put a comma (,) at 
the end of the line to tell REXX that the clause continues on the next line. 


¢ If you use a comma in the middle of a string, REXX interprets the comma as 
part of the string. A comma inside a comment is ignored. 


What is displayed on the screen, when the program shown in Figure 2-7 is run? 


/* Example: there are six clauses in this program */ 
say “Everybody cheer!" 


say i 4a say "AN say "6" say "Bl 
say “Who do we", 
"appreciate?" 


Figure 2-7. RAH.CMD 


If you are not sure, create a file called RAH.CMD, type the program, and run it. 


Types of Clauses 
The three types of clauses are: 


e Null clauses 
e Labels 
© Instructions. 


Null Clauses 
A clause that is empty (a blank line) or consists only of blanks or comments is called 
a null clause. REXX ignores all null clauses, except to check for a comment in the 
first line of a program. This means you can use spaces and blank lines to make your 
program more readable without affecting its performance. 
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Labels 


Labels are symbols that mark positions or portions of a program, internal 
subroutines, condition traps, and so forth. They are distinguished by a trailing colon 
(for example, ERROR:). Except for their use with the CALL and SIGNAL 
instructions and for internal function calls, labels are regarded as null clauses. 


Unlike null and instruction clauses, labels are self-delimiting. They do not require 
semicolons or carriage returns to separate them from other clauses. 


Instructions 


The three types of instruction clauses are: 


Keywords 


Assignments 


Commands 


For More Information 


Clauses that begin with words, such as PULL and SAY, that 
REXX recognizes as instructions. Keywords are not reserved 
words, but the language processor recognizes them by their context 
(see “Variables as Symbols” on page 3-7). Certain keyword 
instructions may comprise one or more clauses, such as the IF 
instruction. 


The keyword instructions are listed alphabetically in the REXX 
Reference. 


Clauses that assign values to variables. An assignment normally 
takes the form symbol = expression. The PARSE instruction and 
its variants PULL and ARG also assign values to variables. Refer 
to Chapter 3, “Variables,” for a description of variable 
assignments. 


Clauses that are processed by other programs. A clause that is an 
expression by itself is interpreted as a command to be passed to the 
current environment (the application that initially called REXX). 
You can also use the ADDRESS instruction to pass commands to 
other environments. Refer to Chapter 5, “Commands,” for a 
description of more commands. 


For a more complete discussion of REXX syntax, refer to “General Concepts” in the 


REXX Reference. 
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Chapter 3. Variables 


Variables are a means of handling changeable information by representing it in terms 
of symbols. This chapter explains why variables are important when writing 
programs and describes the basic rules for using them. 


Basics 
In this chapter: 


Basics 


Handling data with symbols 


Assignments 
Naming variables 
Other assignments. 


Handling Data with Symbols 
One basic requirement of any program is that it must work with information that is 
unknown when the program is written. 


You could write a program that totals a fixed list of numbers. For example: 


say "2 + 3 equals" 2 + 3 


This example displays the result 5 each time you run it, but that is all you would get. 
This is a reliable program but not a very useful one. A program that is more useful 
can process different information each time it is run. You can do this by using 
variables to stand in for values to be processed. A variable is a symbol (one or more 
characters) that represents a value. 


Figure 3-1 shows a program that contains a simple calculation. 


/* the sum of two numbers */ 
say “Type a number:" 
pull first /* waits for entry */ 


say “Type another number: " 
pull second /* waits for entry */ 
say "The sum is" first + second 


Figure 3-1. ADD2NUM.CMD 
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Names and Values 


Assignments 


The following is displayed on the screen, when you run the program. 


[C:\Jadd2num 


Type a number: 
? 


25 


Type another number: 
? 


32 
The sum is 57 


[c:\] 


Two PULL instructions are used, allowing the user to type the two numbers to be 
added and then assign (store) them in the variables first and second. The SAY 
instruction displays the sum of the two. 


The information stored in a variable is called its value. The value can be one or 
more words of text, numbers, or nothing. The value of a variable can change any 
time you want it to. It can be different each time the program is run, or it can 
change many times in a single run. If the value of a variable changes, the name of 
the variable stays the same. It will be easier to remember variables if you choose 
names that are meaningful to you. 


You can think of a variable as a name for the type of values you want it to hold. 


An instruction that stores a value in a variable or changes its value is called an 
assignment. The simplest form of assignment is the equal sign, a REXX clause in the 
form name = value where: 


name is the name you give the variable 

value is the value it will: hold. 

In more formal terms, the syntax of an assignment is in the form symbol = 
expression where: 

symbol is a valid variable name 

expression is the information to be stored, such as a number, a string, or some 


calculation that you want REXX to perform. 


REXX evaluates (computes) the expression and then puts the result of that 
evaluation into the variable called symbol. The assignment instruction means 
“Evaluate the expression and store the result as symbol.” 

In an assignment, you name a variable and give it a value. For example: 


¢ To give a variable called total the value 0, use the assignment total = 0. 


¢ To give another variable, called price, the same value as total, use the 
_assignment price = total. 


e To give the variable called total a new value, the old value of total plus the 
value of something, use the assignment total = total + something. 


3-2 REXX User’s Guide 


So 


In a different type of assignment, pull something, the PULL instruction gives the 
variable something a value that the user types while the program is running. 


Displaying the Value of a Variable 
To display the value of a variable while a program is running, use the SAY 
instruction, as shown in Figure 3-2. 


/* some assignments */ 

amount = 100 /* assigns 100 to AMOUNT 
money = "dollars" /* assigns "dollars" to MONEY 
say amount money /* displays "100 dollars" 
amount = amount + 25 /* adds 25 to AMOUNT 

say amount money /* displays "125 dollars" 


/* Now get some input from the user */ 


say "Type a line, then press the Enter key" /* prompts the user to type */ 
pull anything /* waits for user to press the Enter key*/ 
say "You typed:" anything /* displays the input on screen */ 


Figure 3-2. ASSIGN.CMD 


If you use a SAY instruction with a variable that has not been assigned a value, 
some languages would generate an error. In REXX, the default value of a variable 
is its own name, converted to uppercase letters, as shown in Figure 3-3. 


/* display unassigned variables */ 
say amount /* displays AMOUNT 


say first /* displays FIRST 
say price /* displays PRICE 
say who /* displays WHO 


Figure 3-3. NOASSIGN.CMD 


Note: Another way to display the value of a variable while a program is running is 
with the TRACE instruction, used for correcting programs. Refer to “Tracing 
Evaluation” on page 4-7. 


Naming Variables 
You can name variables almost anything you want. There are a few rules that 
REXX imposes and a few conventions that should be observed. A variable name 
can be any symbol (group of characters), containing up to 250 characters, with the 
following restrictions: 


¢ The first character must be A-Z, a-z, !, ?, or _ . REXX translates lowercase 
letters to uppercase before using them. 


e The rest of the characters may be A-Z, a-z, !, ?, _» -» or 0-9. 


¢ The period (.) has a special meaning for REXX variables. Do not use it ina 
variable name until you understand the rules for forming compound symbols. 
See “Using Compound Symbols” on page 3-8. 


Chapter 3. Variables 3-3 


Here are some tips for good programming practice: 
¢ Give variables names that describe the data they represent. 


¢ Give variables names that are different from REXX keywords or OS/2 
commands. 


e Give variables names that will not be confused with each other. 


¢ Do not abbreviate unnecessarily. It is better that the name is long rather than 
obscure. 


¢ Use each variable for only one purpose. Do not use the same variable for a user 
entry that you used elsewhere to accumulate a total. 


Test Yourself 
Which of the following could be used as the name of a REXX variable? 


9T 
. nine_to_five 
27 


ee 


Answers: 


. OK 

OK 

. Invalid, because the first character is a numeric digit. 
. OK, same as NINE_TO_FIVE 

OK 


AWN 


Other Assignments 
You can also use variables to store information that is unknown when you are 
writing the program. 


Assigning User Input 
One use for variables that has already been discussed is as a holding place for 
information typed by the user. The PULL and ARG keyword instructions are 
commonly used for this purpose. 


The PULL instruction pauses the running of a program to let you type one or more 
items of data, which are then assigned to variables. For example, the PULL 
instruction was used in the program shown in Figure 3-1 on page 3-1 to get two 
numbers to add. 


say “Type a number:" 


pull first /* waits for entry */ 
say “Type another number; " 
pull second /* waits for entry */ 


Each PULL instruction pauses the program and displays a ? to prompt you to type 
a number and press the Enter key. It then assigns the entry to the variable named in 
the instruction. 
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You can also use the PULL instruction to collect more than one item in an entry as 
long as the items are separated by spaces. The four lines in the preceding example 
could be replaced with: 


say "Type two numbers (leave a space between) and press the Enter key" 
pull first second 


The PULL instruction pauses the program so you can type the two numbers to be 
added. When you press the Enter key, PULL reads the two numbers and assigns 
them, in the order they were typed, to the list of variables (first and second). This 
process of reading and separating information is called parsing. 


The ARG instruction is another way to assign data from the user. ARG works 
similar to PULL, except that items are typed at the command prompt with the 
program name. The calculation in the program shown in Figure 3-1 on page 3-1 
could also be done by the program shown in Figure 3-4, which follows. 


/* the sum of two numbers, this time */ 
/* typed at the command prompt 34 


arg first second /*collects entries */ 
say "The sum is" first + second 


Figure 3-4. ADD.CMD 


The following is displayed on the screen, when you run ADD.CMD. 


[C:\Jadd 25 32 
The sum is 57 


Notice that with the ARG instruction the program does not pause. The numbers to 
be added are typed with the ADD command that starts the program. 


Assigning an Expression Result 
The instruction amount = amount + 25 in the program shown in Figure 3-2 on 
page 3-3 shows how variables can represent another type of unknown 
information—data that must be calculated or otherwise manipulated. You can assign 
to a variable the result of a calculation or expression, as shown in Figure 3-5. 


/* area of a 3 by 5 in. rectangle */ 
area = 3 * 5 
say area "sq. in." /* displays "15 sq. in." */ 


/* area of a 5 in. circle */ 

diameter = 5 

radius = diameter/2 

area = 3.14 * radius * radius 

say area "sq. in." /* displays "19.6250 sq. in." */ 


Figure 3-5. AREAS.CMD 


REXX expressions can have very complex forms and they can work with all kinds of 
information. 
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Summary 
This completes “Basics” in this chapter. You have learned how to: 


Assign a value to a variable using the equal sign 
Display the value of a variable 

Name variables 

Assign user input to a variable. 


“Advanced Topics” in this chapter discusses: 


¢ How REXX recognizes and processes variables 
¢ Using variables in ordered groups called arrays 
e Using variables in complex programs. 


To continue with “Basics,” go to page 4-1. 
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Advanced Topics 
In this chapter: 


Advanced Topics 


Variables as symbols 
Using compound symbols 


Variables in programs and subroutines 
Other types of data storage. 


Variables as Symbols 


Variables are part of a class of REXX language elements called symbols. These 
include: 


¢ REXX keywords and instructions 
e Labels used to call internal subroutines (see “CALL Instruction” on page 7-2) 
¢ Constants 
¢ Variables. 
REXX uses the context of a symbol to determine if it is a keyword, a label, or a 


variable. For each symbol it encounters, REXX takes the following steps to 
determine how it will be handled: 


1. If the first token is a symbol and is followed by: 


a. An equal sign (=), the clause is an assignment instruction. The symbol is a 
variable and is assigned the expression that follows the equal sign. 


b. A colon (:), the clause is a label, signalling the beginning of a subroutine. 


2. If the symbol is in the list of REXX keyword instructions or is a keyword used 
in a control structure, such as while or then, REXX interprets the keyword 
accordingly. (See Chapter 6, “Program Control.”) 


3. If the symbol begins with a number, it is a constant (an unchangeable value). 


If none of these steps determine how the symbol is to be handled, REXX evaluates 
the symbol as a variable and replaces the variable name with the stored value of the 
symbol. 


Constants and Variables 
Symbols that begin with a digit (0-9), a period, or a sign (+ or —) are constants. 
They cannot be assigned new values and, therefore, cannot be used as variables. 
Some examples of constants are: 


77 a valid number 

- 6604 begins with a period (decimal point) 

1.2e6 Scientific notation (equal to 1 200 000) 

42nd Not a valid number; its value is always 42ND. 


All valid numbers are constants, but not all constants are valid numbers. The 


symbol 3girls is not a valid number; it cannot be used as a variable name. Its value 
is always 3GIRLS. 
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The default value for a symbol is its own name, translated into uppercase letters. A 
variable that has not been assigned a value contains this default value. 


ae Compound Symbols 
There is a special class of symbols, called compound symbols, in which variables and 
constants are combined to create groups of variables for easy processing. A 
variable containing a period is treated as a compound symbol. Some examples of 
compound symbols are: 


fred.3 
row.column 
array.I.J. 
gift.day 


You can use compound symbols to create a collection of variables that can be 
processed by their derived names. An example of a collection is: 


gift.1 = 'A partridge in a pear tree' 
gift.2 = 'Two turtle doves' 

gift.3 = ‘Three French hens' 

gift.4 = ‘Four calling birds' 


If you know what day it is, you know what gift will be given. Assign a variable 
called DAY a value of 3. 


day = 3 
Then the instruction say gift.day, in the program shown in Figure 3-6 on page 3-9, 
displays Three French hens on the screen. When the program is run: 


1. REXX recognizes the symbol gift.day as compound because it contains a 
period. 


2. REXX checks if the characters following the period form the name of a variable. 
In this example, it is the variable name day. 


3. The value of day is substituted for its name, producing a derived name of gift.3. 


4. The value of the variable gift.3 is the literal string 'Three French hens'. 


If day had never been given a value, its value would have been its own name; day 
and the derived name of the compound symbol gift.day would have been GIFT.DAY. 


3-8 REXX User’s Guide 


Figure 3-6 is a collection of consecutively numbered variables, sometimes called an 
array. 


/* What my true love sent ... */ 


/* First 
gift.1 
gift.2 
gift.3 
gift.4 
gift.5 
gift.6 
gift.7 
gift.8 
gift.9 
gift.10 
gift.11 
gift.12 


assign the gifts to the days */ 
‘A partridge in a pear tree' 
‘Two turtle doves' 

‘Three French hens' 

"Four calling birds' 

‘Five golden rings' 

"Six geese a-laying' 

"Seven swans a-swimming' 
‘Eight maids a-milking' 
"Nine ladies dancing’ 

'Ten lords a-leaping' 
"Eleven pipers piping’ 
‘Twelve drummers drumming' 


/* list all gifts from the 12th day to 
/* the 1st day; refer to the discussion 
/* of loops on page 6-11. 

do day=12 to 1 

say gift.day 

end 


/* now display the gift for a chosen day */ 
say "Type a number from 1 to 12." 
pull day 


/* check for proper input */ 

/* see page 9-1 * 

if \ datatype(day,n) then /* if the entry is not a number */ 
exit /* then exit the program */ 


if day <1 | day > 12 then /* same if it is out of range */ 
exit 


say gift.day 


Figure 3-6. TWELVDAY.CMD 
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Test Yourself 


1. 


Write a program to display the days of the week repeatedly, as: 


Sunday 
Monday 
Tuesday 
Wednesday 
Thursday 
Friday 
Saturday 
Sunday 
Monday 


You will need to create an endless loop, using the DO instruction. (See 
“Repetitive Tasks” on page 6-11 for information about loops.) 


Note: To stop this program, press the Control (Ctrl)+Break keys if you are 
running the program in an OS/2 command prompt session. Select Interactive 
trace on from the Options menu if you are running it in PMREXX. This stops 
any REXX program. 


. Extend this program to display the days of the month, as: 


Sunday lst January 
Monday 2nd January 


Answers: 


1. 


Figure 3-7 shows one solution. 


/* To display the days of the week indefinitely */ 
do forever 


say "Sunday" 
say "Monday" 
say "Tuesday" 


say "Wednesday" 
say "Thursday" 
say "Friday" 

say "Saturday" 


Figure 3-7. DAYS1.CMD 


3-10 REXX User’s Guide 


In view of the preceding discussion, Figure 3-8 shows a solution that uses 
compound variables. 


/* to display the days of the week indefinitely */ 
day.1 
day.2 
day.3 
day.4 
day.5 
day.6 


"Sunday" 
"Monday" 
"Tuesday" 
"Wednesday" 
"Thursday" 
"Friday" 
"Saturday" 


day.7 


do j=1 

say day.j 

if j = 7 then j = 0 
end 


Figure 3-8. DAYS2.CMD 


2. Figure 3-9 shows how to extend the idea using the SELECT instruction. 


/* to display the days of the month for January */ 
day.1 = "Sunday" 

day.2 = "Monday" 

day.3 = "Tuesday" 

day.4 = "Wednesday" 

day.5 = "Thursday" 

day.6 = "Friday" 

day.7 = "Saturday" 


do dayofmonth = 1 to 31 
dayofweek = (dayofmonth+6)//7 + 1 


select 
when dayofmont 
when dayofmont 
when dayofmont 


h then th = "st" 
h 
h 
when dayofmonth 
h 
h 


1 

2 then th = "nd" 

3 then th = "rd" 

21 then th = "st" 
when dayofmont 22 then th = "nd" 
when dayofmont 2 = "rd" 


"st" 


h 

h 

3 then th 

when dayofmonth = 31 then th 
otherwise th = "th" 

end 


say day.dayofweek dayofmonth} {th "January" 
end 


Figure 3-9. MONTH1.CMD 


Senet 
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A Scoreboard Array 
Figure 3-10 shows how you can use compound symbols to collect and process data. 
In the first part of the program, the first player’s score is entered into SCORE.1, the 
second player’s into SCORE.2, and so on. By using compound symbols, the SCORE 
array is processed to give the result in the required form. 


This is a scoreboard for a game. Any number of oF | 
players can play. The rules for scoring are these: */ 
* 

Each player has one turn and can score any number of */ 
points; fractions of a point are not allowed. The */ 
/* scores are entered into the computer and the program */ 
/* replies with *} 
he wf 
/ the average score (to the nearest hundredth of */ 
a point) */ 
the highest score =) 

the winner (or, in the case of a tie, 

the winners) 


say "Type the score for each player in turn. When all" 
say "have been typed, enter a blank line!" 
say 
n=1 
do forever 
say "Please type the score for player "n 
pull score.n 
select 
when datatype(score.n,whole) then n=n+tl 
when score.n="" then leave 
otherwise say "The score must be a whole number." 
end 
end 


/* now n = number of players */ 


do player = 1 ton 
total = total + score.player 
end 


say “Average score is", 
format(total/n,,2,0) /* format "total/n" with 
/* no leading blanks, +) 
/* round to 2 decimal places,*/ 
/* do not use exponential 
J notation 


/* continued ... 


Figure 3-10 (Part 1 of 2). GAME.CMD 


3-12 REXX User’s Guide 


Stems and Tails 


highest = 0 
do player = 1 ton 
highest = max(highest,score.player) 
end 
say "Highest score is" highest 


Now compute: 

* W, the total number of players that have a score 
equal to HIGHEST 

* WINNER.1, WINNER.2 ... WINNER.W, the id-numbers 
of these players 


/* number of winners 


do player = 1 ton 
if score.player = highest then do 
w=wtil 
winner.w = player 


then say "The winner is Player #"winner.1 
else do 
say "There is a draw for top place. The winners are" 
do p=1 tow 
say " Player #"winner.p 
end 
end 
say 


Figure 3-10 (Part 2 of 2). GAME.CMD 


The stem of a compound symbol is the portion up to and including the first period. 
That is, it is a valid variable name that ends with a period. 


The stem is followed by a tail, comprised of one or more valid symbols (constants or 
variables) separated by periods. You can refer to all the variables in an array by 
using the stem of the array. For example: 


player. = 0 
say player.1 player.2 player.golf /* displays '000' */ 


It is often convenient to set all variables in an array to 0 in this way. 
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Filling a Two-Dimensional Array 


You can have more than one period in a compound symbol. For example, here is 
the beginning of a program for playing checkers. BOARD is a 2-dimensional array, 8 
squares by 8 squares. The squares on the board are called BOARD.ROW.COL and there 
are 64 of them. Figure 3-11 shows how the men are set at the start of the game. 


Row 


Column 


Figure 3-11. Checker Board 
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Figure 3-12 shows a program that sets the men on the checker board. 


This program simulates a board on which the game of 
checkers can be played. 


/* In the internal representation, Red's "men" are 
/* represented by the character "re" and Red's "kings"  */ 
/* by the character "R". Similarly, Black's "men" and */ 
"kings" are represented by "b" and "B". */: 


board.1. 

end 

do col = 2 by 2 to 8 
board.2.col = "r" 

end 

do col = 1 by 2 to 7 
board.3.col = "r" 

end 

do col = 2 by 2 to 8 
board.6.col = "b" 

end 

do col = 1 by 2 to 7 
board.7.col = "b" 

end 

do col = 2 by 2 to 8 

board.8.col = "b" 


end 


Figure 3-12. CHECKERS.CMD 


Variables in Programs and Subroutines 


Special Variables 


Here are some considerations for using variables in REXX programs. For more 
information about variables, including how programs written in other languages can 
use REXX variables, see the REXX Reference. 


REXX has three special variables that are assigned values automatically as needed: 


RESULT holds the value set by a RETURN instruction in a subroutine. (See 
“RETURN Instruction” on page 7-3.) 


SIGL holds the line number of the last call to a label. (See “CALL 
Instruction” on page 7-2 and “SIGNAL Instruction” on page 7-14.) 


RC holds the return code from the last OS/2 command issued. (See 
“Reading Return Codes” on page 5-9.) 
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SYMBOL()Function 


It is sometimes useful to check whether a symbol has already been used as a name of 
a variable. To do this, use the SYMBOL( function, SYMBOL(name), where name is 
the name of the symbol that you want to test. The SYMBOL( function returns: 


BAD _ if name is not a valid symbol 
VAR _ if name has been used as a variable in the program 
LIT if the symbol name is a valid variable that has not yet been assigned a value, 


or if it is a constant symbol (such as a number). 


One use of SYMBOL( is to ensure initialization of a variable; that is, making certain 
that the variable is set to a proper starting value before it is used in an operation. 
For example, you can use SYMBOL( to make sure REXX does not try to add a 
variable called payment to one named cash until cash has been set to a numeric 
value. 


if symbol("CASH") = "LIT" then cash = 0 
cash = cash + payment 


Put CASH in quotes to test the symbol rather than its value. Notice what happens if 
the argument of SYMBOLAO is not in quotes. 


cash = 100 

say symbol (CASH) /* displays 'LIT', because the value */ 
/* of CASH is 100 - a constant *] 

say symbol ("CASH") /* displays 'VAR', because CASH is */ 
/* the name of a variable a) 


Without the enclosing quotes, CASH is treated as a variable and its value is 
substituted before the function is performed. 


PROCEDURE Instruction 
When you are writing a subroutine, you may not know the names of all the variables 
in the main program. You could check by reading the entire program every time 
you wanted to create a new name, but this is tedious and prone to error. To delete 
all variables, for the sake of the subroutine, use the REXX PROCEDURE 
instruction. 


Once this instruction has been processed, new variables can be created that are 
regarded as different, even if some of them have the same names as variables that 
existed before the PROCEDURE instruction was processed. 


When a RETURN instruction is processed, the new variables are deleted and the 
original variables are restored. 


A PROCEDURE instruction can only be used within an internal routine. It can be 


used only once and must be the first instruction in the routine. For further details 
on the PROCEDURE instruction, see the REXX Reference. 
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Figure 3-13 shows count being used for two separate purposes. 


count = 999 
list =3 4567 


CALL average list 


/* At this point: COUNT = 999 
RESULT = 5 


AVERAGE: 

/* The argument must be a list 

/* of numbers, delimited by blanks. 
/* The average is returned. 


PROCEDURE 


/* At this point the value of LIST 
/* would be LIST 
/* and COUNT would be COUNT. 


ARG inputlist 
sum = 0 
do count = 1 to words(inputlist) 
sum = sum + word(inputlist,count) 
end 


RETURN sum/words (inputl ist) 


Figure 3-13. PROCEDURE.CMD 


PROCEDURE EXPOSE Instruction 
To share a limited set of variables between the main routine and the subroutine 
(leaving all the other variables protected), use PROCEDURE EXPOSE name [name] 
[name]..., where name is the name of a variable to be shared. 


You can also name a list of variables to be shared. By specifying the stem of an 
array (PROCEDURE EXPOSE player.), you can share all of the variables therein. 


For further details, see the discussion of the PROCEDURE instruction in the REXX 
Reference. 
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Other Types of Data Storage 
Variables are the principal means of manipulating data within a REXX program. 
REXX features other ways to work with data outside the program and to share data 
with other programs, such as: 


Queues store sequential data in memory. 


Files provide more permanent storage on disk. 


Refer to Chapter 10, “Input and Output,” for the REXX instructions and functions 
that work with external data. 
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. Chapter 4. Expressions 


An expression is a description of information that you want REXX to compute. It 
can be as simple as adding two numbers or as complex as you want to make it. 


Basics 
In this chapter: 
Basics 


Transforming data 
Operator precedence 
Using functions 
Comparing data 


ad 
> 
> 
> 
> 
> 
> 


Tracing evaluation. 


Transforming Data 


Using comparisons for program control 
Using expressions in instructions 


The process of REXX reading an expression and producing a result is called 
evaluating the expression. REXX has many rules for evaluating expressions. 


Expressions are made up of terms, the data that is computed, and operators, the 
computations that are performed. 


Some examples of REXX expressions are: 


J* some arithmetic 

say 3 + 2 /* displays 
say 3 * 2 /* displays 
say 3 2 /* displays 
say 3/12 /* displays 
7* some literal strings 
say "box" "car" /* displays 
say "box""car" /* displays 


say "box"!!"car" /* displays 


/* some variables 

x = 6 

y=7 

say x + y /* displays 
X=xt+y 

say X /* displays 


mp" 
"6" 
"3 2 u 
"32" 


"box car" 
"box "car" 
"boxcar" 


i] 13" 


un 13" 


"i 


aif 
*/ 
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Terms 


The terms of an expression are the individual pieces of information that you want 
REXX to work on. The types of terms that make up expressions are: 


Numbers 


Literal strings 


Variables 


Function calls 


Basic Operators 


Strings that REXX can calculate. REXX recognizes them as 
constant values. For example: 


25 3.14159 -6 1989 


Anything within matched quotes REXX accepts as is. For 
example: 


"Wednesday" 'C:\PROGRAMS\' "Q9 June 89" 


Symbols that stand for changeable data. When you use a 
variable in an expression, REXX evaluates it and uses its value 
as the expression. For example: 


date = 30 /* stores the number 30 sf 
/* in the variable DATE */ 
month = "March" /* stores the literal string ot 


/* "March" in the variable MONTH */ 


say month date /* displays "March 30” on screen */ 


These are special computations, some built into REXX, others 
that you can create. When you use a function call in an 
expression, REXX performs the function’s calculation first, then 
uses its result as the expression term. For example: 


say time() /* displays the current time */ 


say substr("REXX",2,1) /* displays "E" on screen; */ 
/* i.e., 1 character from the */ 
/* string "REXX" beginning */ 
/* with the 2nd character fb 


The most commonly used operators are those used for arithmetic and concatenation. 
Arithmetic performs adding, subtracting, multiplying, and dividing. Some examples 
of arithmetic operators are: 


/* add, subtract, multiply ... *y 
say 14 + 5 /* displays "19" x; 
say 14 - 5 /* displays "9" *y 
say 14*5 /* displays "70" */ 
/* ... and three ways to divide */ 
say 14/5 /* displays "2.8" - */ 

/* normal division */ 
say 14% 5 /* displays "2" - the */ 


say 14 // 5 
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/* integer result only */ 


/* displays. "4" -the */ 
/* remainder only */ 


For more information about using numbers in REXX, see Chapter 9, “Arithmetic.” 


- Concatenation joins strings together with: 


* A single blank, if you leave one or more blanks between the terms of an 
expression 


¢ No intervening blanks, if you put the terms together. This is called abuttal. For 
abuttal to work, REXX must be able to recognize the terms as separate. 


¢ No intervening blanks, if you use the concatenation operator vbar.| (two vertical 
bars). Use this operator where abuttal does not work (such as with two 
variables) or to state exactly how you want the strings joined. 


Note: On the OS/2 operating system, REXX uses ASCII character 124 as the 
concatenation operator and as the logical OR operator. This character 
may appear as a solid vertical bar (|) or as a split vertical bar (|). The 
character on the screen may not match the character engraved on the 
key. If you receive error 13, invalid character in program on an 
instruction including a vertical bar character, make sure this character is 
ASCII 124. 


Some examples of concatenation are: 
say "slow" "coach" /* displays ‘slow coach' */ 


adjective = "slow" 


say adjective "coach" /* displays ‘slow coach’ +) 
say adjective"coach" /* displays 'slowcoach' */ 
/* (using abuttal) i 
say "slow"||"coach" /* displays 'slowcoach' */ 
say 45 /* displays '4 5' */ 
say 4||5 /* displays '45' | 
tens = 4 
units = 5 
say tensunits /* displays 'TENSUNITS' (abuttal */ 
/* produces a new symbol) =] 
say tens||units /* says '45' id 
say (4||5) / 3 /* displays '15' */ 


Concatenation works with numeric as well as non-numeric strings. In the previous 
example, parentheses are used to force REXX to concatenate the 4 and the 5 before 
dividing the result by 3. 


Operator Precedence 
Without parentheses in the previous example, REXX would have performed the 
division first, then the concatenation. It would divide 5 by 3 (result 1.6666667) and 
then join the 4 in front. For example: 


say 4|{5 / 3 /* displays '41.6666667' */ 


REXX gives precedence, or priority, to division over concatenation. This means that 
REXX has a set of built-in rules for the order in which operations are performed. 
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Basically, REXX evaluates an expression by reading it from left to right. Before it 
does, it takes into account: 


e Any parentheses you have used. 


¢ The built-in operator precedence of REXX, which means some operations get 
higher priority than others, no matter where they are in the expression. 
Multiplication and division come before addition and subtraction; addition and 
subtraction before concatenation. See page 4-10 for a listing of REXX operator 
precedence. 


You can always use parentheses to override the precedence rules of REXX. It is a 
good practice to use parentheses because they help make your program more 
readable. 


Using Functions 
For more extensive computations, REXX has built-in functions. A function always 
returns (produces) a value. This value is represented in an expression by a symbol 
referred to as a function call. All function calls consist of a name, followed by 
parentheses. There is no space between the name and the first parenthesis. For 
example: 


Tength("Madison") 


e The value you want the function to work on is called the function’s argument. 
In this example, the argument is the literal string "Madison". 


e The value a function call produces is its return value. The return value depends 
on what you put inside the parentheses. In this example, the LENGTHQ 
function returns the value 7, the number of characters in Madison. 


The instruction, say length("Madison Avenue") displays the return value 14. 


The argument of a function can itself be an expression. For example, the function 
ABSQO returns the absolute (positive) value of a given number. Given an arithmetic 
expression as an argument, ABS() first evaluates the expression and gets the result. 
In the following example, the ABSQ function calculates the result -98 and returns 
the absolute value of that result, which is 98. 


say abs(2 - (50 * 2)) /* displays '98' */ 

If a function allows for or requires more than one argument, the arguments are 
separated by commas. For example: 

say copies("=",80) /* displays 80 "=" characters */ 


Some functions need no arguments. For example, the DATE( function gets the 
date from your system clock. It has several optional arguments. 


say date() /* displays '15 Mar 89' */ 
say date(w) /* displays ‘Wednesday’ */ 
say date(s) - /* displays '19890315' Ff 


The DATATYPEO function reports the type of data an expression evaluates as: 


stri = "ABC" /* a character string */ 
str2 = "12" /* a numeric string *] 
say datatype(str1) /* displays '‘CHAR' =] 
say datatype(str2) /* displays ‘NUM’ +] 
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Comparing Data 


You can include a function call anywhere within an expression. REXX performs the 
function’s computation and then substitutes the return value for the function call 
before it evaluates the entire expression. 


For more information about functions, see Chapter 7, “Program Structure.” 


Refer to the REXX Reference for descriptions of the REXX built-in functions. 


Comparisons test data rather than manipulate it. The following is an example of a 
comparison in a program (see Figure 2-1 on page 2-1). 


if who = "" then say... 


What happened next in the program depended on the test: was the variable who 
empty? 


Comparisons are performed using the following operators: 


a 


The comparison operators can be combined so that >= stands for greater than or 
equal and \>= means not greater than or equal (same as <). 


The backslash character (\) negates a comparison operator, turning equal to not 
equal and so on. This character is also used for not in expressions generally. (See 
NOT Operator (\) on page 4-17.) 


The equal sign (=) can have different meanings in REXX depending on its position 
in a clause. For example: . 


amount = 5 /* The variable AMOUNT gets the value 5 ) 
say amount = 5 /* Compare the value of AMOUNT with 5 */ 
/* If they are the same, displays '1' */ 
/* Otherwise, displays 'Q' a) 


The rule is that a clause beginning with symbol = ... is an assignment. An equal 

sign anywhere else in a clause usually stands as a comparison operator. There are 
exceptions. The equal sign has a special use in the PARSE instruction, and it is a 
character, not an operator, in a comment or literal string. 
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Testing for True or False 


The result of a comparison expression is either true (1) or false (0). For example: 


/* some comparisons */ 
say 5=5 


say 5 <5 
say 5 = 4 
say2+2=4 
say2+2=5 


howmuch = 2 + 3 


say "apples" = "oranges" 


fruit = "oranges" 


/* displays '1' 
/* displays '0' 
/* displays '0' 
/* displays '1' 
/* displays '0' 


/* assigns the sum 
/* of 2 and 3 to the 
/* variable HOWMUCH 
/* displays 'O' */ 


/* assigns the string 
/* “oranges" to the 


/* variable FRUIT 
say fruit = "apples" /* displays '0' 
say fruit = "oranges" /* displays '1' 
say howmuch fruit /* displays "5 oranges" 
say howmuch fruit = "4 oranges" /* displays 'O' 
say hownuch fruit = "5 plums" /* displays '0' 
say howmuch fruit = "5 oranges" /* displays '1' 


Combining Expressions 


eh 
*/ 
*/ 


It is often useful to combine two or more comparisons to find a single true-or-false 
value. You can have REXX evaluate a set of comparisons and compute an overall 
value of 1 or 0 for the set. You can combine comparisons so that REXX evaluates 


them as: 


© True (1) only if all of the comparisons in the set evaluate as 1, but false (0) if any 
one or more of them evaluates as 0. This is called an AND condition. To 
combine comparisons this way, use the AND (&) operator. For example: 


fruit = "grapes" 
howmuch = 10 

say fruit 
say fruit 
say fruit 


"apples" & howmuch 
"grapes" & howmuch 
"grapes" & howmuch 


10 /* displays 'O' 
5 /* displays '0' 
10 /* displays '1' 


| 
of 
*f 


Only in the third example are both of the comparisons true, so only, then, is the 
combined result evaluated as 1. 
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e True (1) if any one or more of the comparisons in the set evaluate as 1, and false 
(0) only if all the comparisons evaluate as 0. This is called an OR condition. To 
combine comparisons this way, use the OR (|) operator. For example: 


fruit = "grapes" 
howmuch = 10 


say fruit = "apples" | howmuch = 10 /* displays '1' */ 


say fruit = "grapes" | howmuch = 5 /* displays '1' */ 
say fruit = "grapes" | howmuch = 10 /* displays '1' */ 
say fruit = “apples” | howmuch = 5 /* displays '0' */ 


Both comparisons, individually, had to evaluate as 0 in order for their combined 
value to be 0. 


Using Comparisons for Program Control 
REXX has a set of instructions that control the program and choose the action a 
program is to take in a given situation. That situation is determined by 
comparisons. 


Instructions, such as IF expression THEN ..., must be given an expression that 
computes to @ or 1. In the example of IF...THEN..., a result of 1 means the clause 
following THEN is processed; a result of © means that it is not processed. 


The following two examples give the same result. 
ready = "YES" 


if ready = "YES" then ... 


or 


ready = 1 


if ready then... 


You can use whichever form you prefer. 


For more information about how comparisons can control a program’s processing, 
see Chapter 6, “Program Control.” 


Using Expressions in Instructions 
The REXX Reference and the online OS/2 Procedures Language/2 REXX provide an 
alphabetical listing of all REXX instructions and their syntax. Where the syntax of 
an instruction calls for or allows an expression, you can use any of the rules 
described here. 


Tracing Evaluation 
If your program produces unexpected results, the problem may be that an expression 
was mis-stated. When your program will not run, use the TRACE instruction. 
TRACE displays how REXX evaluates expressions while the program is actually 
running. The options most often used are: 


TRACE Intermediates Displays the immediate result of each operation. 


TRACE Results Displays only the final result of each expression, after it 
has been evaluated. 
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When a TRACE instruction is being interpreted, the first letter of the option 
determines the type of tracing that is switched on; the rest of the word is ignored. 


For example, to TRACE intermediate results for an expression, you could write: 


TRACE I 
- expression 


Figure 4-1 shows a program that uses the TRACE I instruction. 


/* Example: to show how an expression */ 
/* is evaluated, operation by operation */ 
x=9 
y=2 


trace I /* Switch on tracing. */ 

if x +1> 5 * y then If the comparison 
evaluates as '1' 

say "x is big enough." /* ...display this. 


Figure 4-1. TTRACE.CMD 


The following is displayed on the screen when you run the program. 


[C:\] ttrace 
6*-* Ifxt+t1l>5*y 
>Y> il ie) ” 
>L> ul 1 " 


>0> u“ 10 " 


>L> u“ 5 u 
>V> it 2 u 
>0> it 10 iL} 


>>> ft 0 is 


The symbols mean: 


*_* An instruction is being traced. The number on the left is the line number in 
your program. 


>V> Value of a Variable. 
>L> Value of a Literal. 
>0> Result of an Operation. 


>>> The final result of the evaluation. 
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Summary 


The output information below Figure 4-1 on page 4-8 shows that the final result is 
false (0). Because the IF expression is false, the THEN clause is not processed. 


You may not need a trace of every intermediate result. For example, to display only 
the final evaluation results, use TRACE results. 


TRACE R 
ee. expression 


Figure 4-2 shows a program that uses the TRACE R instruction. 
/* Example: to show how an expression is evaluated, 


/* operation by operation using TRACE R 
x =9 


y=2 


trace R /* Switch on tracing. 

if x +1>5 * y then If the comparison 
evaluates as '1' 

say "x is big enough." ...display this. 


Figure 4-2. RTRACE.CMD 


The following is displayed on the screen when you run the program. 


[C:\] rtrace 
6*-* ifxt1l>5*y 


[c:\] 


>>> Lt] 9 i 


Here too, the symbol >>> indicates the final result. Again, the final result is false (0). 
Because the IF expression is false, the THEN clause is not processed. 


This completes “Basics” in this chapter. You have learned how to: 


Use basic REXX arithmetic 

Join strings by concatenation 

Test data using comparison operators 

Use trace evaluation while a program runs. 


“Advanced Topics” in this chapter discusses: 


e Operator precedence 

¢ Using parentheses 

¢ Manipulating strings with functions 
¢ More about comparisons. 


To continue with “Basics,” go to page 5-1. 


Chapter 4. Expressions 4-9 


Advanced Topics 


In this chapter: 
Advanced Topics 


Precedence 

Using parentheses 

More about numbers 
Concatenation 

Substring functions 
Comparisons 

Translating and converting data. 


> 
> 
> 
> 
ad 
> 
> 


Precedence 


When evaluating an expression, REXX reads the operations from left to right. But 
some operators are given a higher precedence (priority) than others and are 
processed first regardless of their position. The complete order of precedence of the 
operators by group (highest priority at the top) is: 


Prefix operators \- + 
Power ic 

Multiply and divide */% |/ 

Add and subtract a 
Concatenation " "|| abuttal 
with/without blank 

Comparison operators == = \== 


<> >= \< 
>>= \<< 
<= \> <<= 
\>> 

Logical and & 

Logical or | && 


(inclusive/exclusive) 


Note: For the OS/2 operating system, |} can also be used as the concatenation 
operator and as the logical OR operator. See “Basic Operators” on page 4-2 
for additional information. 


From this list, you can determine the sequence of operations for any expression. For 
example: . 


Say 3 +2*5 /* displays '13' */ 


Because multiply (*) has a higher priority than add (+), the multiply operation is 


done before the operation on its left. Similarly, because add (+) has a higher 
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priority than concatenate (blank), the add operation is done before the concatenate 
operation. For example: 


Say 3 2+2 5 “ /* displays '3 4 5' */ 


Using Parentheses 
You can use parentheses to force evaluation in a different order since expressions 
inside parentheses are evaluated first. For example the value of: 


6-441. is 3. 
6-(4+1) is 1. 
342/2+3 is 55. 
3 +(2|12)+ 3 is 28. 


Test Yourself 
What is the value of: 


. 4+ 20 “tailors” 

. 24= 4+ 20 

“eggs” = “eggs” & 2*2 = 4 
37275 

. 3 || 74+7 

. 3(2+2) 

. (24+2)3. 


INAUARWN 


Answers: 


1. 24 tailors (add before concatenate) 

2. 1 (add before comparison) 

3. 1 (comparison before AND, multiply before AND, comparison before AND) 

4. 7.5 (operators that have the same priority are processed left to right) 

5. 314 (add before concatenate) 

6. calls the function 3 with the argument 4 (or gives a syntax error if a function or 
subroutine named 3 does not exist) 

7. 43 (evaluate expression in parentheses first; then do the abuttal). 


More about Numbers 
REXX regards everything in a program as a string to be evaluated. REXX treats 
certain strings as numbers that can be calculated, such as: 


e A number begins with a digit, decimal point, or sign (+ or —). 
¢ Powers of 10 are indicated by E. These are called floating point numbers. 
e Numbers may be in quotes, and spaces are allowed around the plus or minus 


sign. 


For more information about valid numbers, see “About REXX Numbers” on 
page 9-1. 


Concatenation 
The three concatenation operations are: 


e Leave one or more spaces between the terms. REXX joins the terms with a 
single blank. 


e Put the terms together with no space. You can do this so long as REXX can 
recognize the terms as separate 
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¢ Use the || operator to join the terms without a blank. 


For the OS/2 operating system, |} can also be used as the concatenation 
operator. See “Basic Operators” on page 4-2 for further information. 


Substring Functions 
The following two substring functions are useful when working with strings. 


Getting Pieces of Strings 
To select a part of a string (a substring), use the SUBSTRO function. For example: 


substr(string,n) 
substr(string,n, length) 


where: 
string is the string from which the substring is taken. 


n is the position of the character in string that is the first character of the 
substring. (Characters in a string are numbered 1,2,3....) 


length (optional); is the number of characters in the substring. If you omit it, the 
rest of string (from the nth position to the end) is returned. 


An example using the SUBSTRO function is: 


say substr('revealing',1,6) /* displays 'reveal' */ 
verb = substr('revealing',1,6) /* stores 'reveal' */ 
/* in avariable */ 


say substr(verb,2) /* displays 'eveal' */ 
say substr(verb,2,3) /* displays 'eve' */ 
say substr(verb,3,4) § /* displays 'veal' */ 


Finding Lengths of Strings 
To find out the length of the result of any string or string expression, use the 
LENGTH() function, length(n), where n is the number of characters in the string. 
For example: 


verb = "reveal" 
say length(verb) /* displays '6' st 
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Figure 4-3 shows a program that uses these two functions. The program checks a 
file name typed by a user. 


/* Checking a file name */ 

say "Type a file name" 

pull fname". "ext /* Pull reads the file name 
/* up to the period (if an 
/* extension is entered) 


if length(fname) > 8 
then 
do 
fname = substr(fname,1,8) 
say "The file name you typed was too long. ", 
fname "will be used." 
end 


Figure 4-3. CHKFNAME.CMD 


For more information about substrings, see “String Functions” on page 8-13. 


Parsing 
Another way to manipulate and analyze string expressions is by parsing. See 
Chapter 8, “Parsing.” 


Comparisons 
Comparisons are performed using these operators: 


= (equal) 


\= or <> or >< (not equal) 


> (greater than) 

\> (not greater than) 
< (less than) 

\< (not less than). 


Comparing Numbers 
Use comparison operators in an expression to compare the terms. The result is 1 if 
the comparison is true; 0 if the comparison is false. 


For strings that are numbers, on which REXX can perform arithmetic, comparisons 
work differently. If both the terms being compared are numbers, comparison is 
numeric, rather than character-by-character. For example the value of: 


5 > 3isl (true) 
2.0 = 002is1 (true) 
3E2 < 299 is0 (false). 
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Comparing Characters 
Comparing characters is performed by using one of two methods, normal comparison 
or strict comparison. Normal comparison ignores leading and trailing blanks and 
compares character-by-character. Strict comparison compares character-by-character 
including any blanks. 


The value of a character is less than another character according to this sequence of 
lowest to highest value. 


Lowest ——_________________—————» Highest 


blank 
aes special characters 
0...9 numbers 
ise40 special characters 
A...Z uppercase letters 
eh special characters 
a...Z lowercase letters 
{...8 special characters 
‘ 
Highest 


Note: Special characters are mixed between the previously listed categories of 
numbers and letters as shown. Only unaccented characters and numbers are in 
numerical order in any of the code pages supported by the OS/2 program. All 
characters are compared through pure binary sorting according to their order in the 
code page you are using. For more information on the special characters for the 
primary code page you are using, see Keyboards and Code Pages. 


Normal Comparison 
If either of the terms is not a number, leading and trailing blanks are ignored. The 
shorter string is padded on the right with blanks and then the strings are compared 
from left to right, character-by-character. If the strings are not equal, the first pair 
of characters that do not match determine the result. 


For example, if" Cheese" is compared with "Chalk ": 


leading blanks 
ignored 


14 
| Ielmelesle 


lt | 
7. nie ‘a' < 'e', so 'Chalk' << '' Cheese' 


shorter string 
ic} a} a} padded with blanks 
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Test Yourself 
1. What is the value of each of the following expressions? 


“3” < “five” 
. “Kilogram” < “kilogram” 
“a” > ar «84 
66 99 66sp>> 
qv> 
“Qa” > Q” 
66ey99 > e399 


moaannrfs 


2. What is displayed on the screen when the program shown in Figure 4-4 is run? 


/* A fair comparison */ 


say "Apples" = "Apples" 


Figure 4-4. FAIR.CMD 


Answers: 
1. All are 1 (true). 


2. The following is displayed on the screen; because “Apples” is equal to “Apples”, 
the result is 1 (true). 


[C:\] fair 
1 


[c:\] 


Strict Comparisons 
By using strict-comparison operators, we can specify character-by-character 
comparisons, with no padding of either of the strings. They do not try to perform 
numeric comparisons because they test for an exact match between the two strings. 


To find out whether two strings are exactly equal, use the double-equal sign (== 
operator. For example: 

The value of “cookies” = ” cookies” is 1 (true) 

The value of “cookies” \= ” cookies” is 0 (false) 

The value of “cookies” = = ” cookies” is 0 (false) 

The value of “cookies” \= = ” cookies” is 1 (true) 


Blanks are Jower in the ASCII sequence than letters. Strict comparison compares the 
leading blanks in its evaluation. 
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L 


To find out whether two strings are exactly greater than or exactly less than, use the 
double-greater-than (>>) and double-less-than (<<) operators. A character is less 
than another character if it comes earlier in the sequence, see “Comparing 
Characters” on page 4-14. For example the value of: 


“cookies” > > “carrots” is 1 (true) 
“$10” > > “nine” is 0 (false) 
“steak” < < “fish” is 0 (false) 

” steak” << “steak” is 1 (true). 


Since the blank is lower in the sequence of characters, " steak" is strictly less than 
"steak". 


See the difference now when we strictly compare " Cheese" and "Chalk": 


leading blanks 
counted 


14 
| lelselelsle 


* 


a blank < 'C' so '' Cheese' << 'Chalk' 


c}n}a}]i no padding of the 


shorter string 


Strict-comparison operators are especially useful when you want to compare strings 
for leading and trailing blanks. 
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Boolean Operators 


Strict comparison is not usually applied to numeric strings, because the reason for 
such a comparison is generally to compare values rather than characters. Given that 


x = "2" andy = "+2", the value of: 


x = y is | (true) 

x \= y is 0 (false) 

x == y is 0 (false) 

x \== yis | (true). 
Strict comparison is also useful if you want to check for nonsignificant zeroes or 
exponential notation. For example, the value of: 

32.000 = 32 is 1 (true) 

32.000 = = 32 is 0 (false) 

000000 = 0E0000 is 1 (true) 

000000 = = 0E0000 is 0 (false). 


The logical or Boolean operators modify and combine expressions. The Boolean 
operators are: 


° NOT Operator (\}—A not operator (\) placed in front of a term changes its value 
from true to false or from false to true. 


A NOT operator (\) reverses the result of any comparison it precedes. An 
expression that REXX otherwise evaluates as 1 is changed to 0 when you put 
the NOT operator in front of it. Similarly, an expression that REXX would 
otherwise evaluate as 0 is evaluated as 1 when preceded by a NOT operator. 
For example: 


say \ 0 /* displays '1' */ 
say \ l /* displays ‘0' */ 
say \ 2 /* returns a syntax error */ 
say \ (3 = 3) /* displays '0' */ 
fruit = "oranges" /* assigns "oranges" to +) 

/* the variable FRUIT */ 
say fruit = "oranges" /* displays '1' | 
say fruit = "apples" /* displays 'O' *) 
say \(fruit = “apples") /* displays ‘1' */ 
say \(fruit = "oranges") /* displays 'O' *) 


To combine comparisons, to get the overall true-or-false value of more than one 
condition, use the logical operators AND and OR. 


e AND Operator (&)—To write an expression that is only true when every one of 
a set of comparisons is true, use the AND (&) operator. For example: 


If ready = "YES" & steady = "RIGHT" 
then say "GO" 


This means that if ready has a value of YES and steady has a value of RIGHT, 
then say GO. Otherwise, do nothing. 


e Inclusive OR Operator (|)—The single vertical bar (|) is an inclusive OR. It 
combines comparisons so that the whole expression evaluates as 1 (true) if any of 
the comparisons are true. 
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To write an expression that is true when at least one of a set of comparisons is 
true, use the inclusive OR (|) operator. For the OS/2 operating system, |! can 
also be used as the concatenation operator and as the logical OR operator. See 
“Basic Operators” on page 4-2 for additional information. 


For example: 


If ready = "YES" | steady = "RIGHT" 
then say "GO" 


This means that if either ready has a value of YES or steady has a value of 
RIGHT, or both, then say G0. Otherwise, do nothing. 


e Exclusive OR Operator (&&)—The double ampersand (&&) is an exclusive OR. 
It combines comparisons so that the expression evaluates as 1 (true) when one 
and only one of the comparisons is true. 


city = "NEW YORK' 


state = 'NJ' 

local = 'NO' 

if city = 'NEW YORK' && state = 'NJ' then 

local = 'YES' 

say local /* displays 'NO' */ 


Test Yourself 
What is displayed on the screen, when the program shown in Figure 4-5 is run? 


/* Example: comparing numbers */ 
dozen = 12 

score = 20 

say score = dozen + 8 


/* Using the AND operator */ 
say dozen = 12 & score = 21 


/* Using the OR operator */ 
say dozen = 12 | score = 21 


Figure 4-5. MEASURES.CMD 


Answer: The following is displayed on the screen when you run the program. 


[C:\] measures 
1 


0 
1 
[c:\] 


For the expression using the AND operator: 
¢ The first comparison (dozen = 12) produces the result 1 (true). 


e The second comparison (score = 21) produces the result 0 (false). 


The result of the AND operation is 0 (false). The AND operation evaluates as 1 
(true) only when both comparisons evaluate as 1. 
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For the expression using the OR operator: 
e The first comparison (dozen = 12) produces the result 1 (true). 
e The second comparison (score = 21) produces the result 0 (false). 


The result of the OR operation is 1 (true). The OR operation evaluates as 1 (true) 
when at least one of the comparisons evaluate as 1. 


Translating and Converting Data 


Number Systems 


REXX functions can translate data from one character set to another. Translation 
is especially useful when a REXX program must process output that is in binary or 
hexadecimal form. If you are a beginning programmer, you may not need these 
functions. However, you may want to read this discussion if you want to use REXX 
with your printer or with other programs. 


For more information on how REXX works with external data in files and queues, 
refer to Chapter 10, “Input and Output.” 


For more information about the following functions, refer to “Functions” in the 
REXX Reference. 


The OS/2 program uses a standard character set, called the ASCII (American 
Standard Code for Information Interchange) set, to represent information. In 
ASCII, each character has a unique number that may be represented in different 
ways. For example, the character ? has the value 63. 


Computers operate in binary terms such as on and off, yes and no, true and false. 
They regard numbers in the same way. The decimal number 63 in a binary 
numbering system is 00111111. Each digit stands for a power of two. In this 
example the binary number stands for 32+16+8+4+2+1, or 63. That is how a 
computer sees a question mark. Every character is rendered as a byte: a set of eight 
binary digits, each having a value of 0 or 1. Binary numbers are difficult for people 
to read. 


Programmers use another numbering system, based on 16 digits, called hexadecimal 
or hex, for short. Each digit of a hex number represents four binary digits. 
Therefore, a byte can be represented by just two digits. The 16 possible hex digits 
are: 


F (hex) 


6123 456789ABC ODE 

@ 12 3 4 5 6 7 8 9 1011 12 13 14 15 (decimal) 

The hexadecimal equivalent of decimal 63 is 3F. That is 3*16 plus 15*1, or 63, 
which translates to the question-mark (?) character. 


Note: For some decimal or hexadecimal numbers, the ASCII character is different, 
depending on the code page that you are using (see Keyboard Layouts). 


In addition to ASCII and decimal numbers, REXX also accepts strings expressed in 
these forms: 


Binary If a string is to be expressed as one or more binary numbers, enclose 
it in matching quotes and put the letter B (uppercase or lowercase) 
immediately following the closing quote. Spaces within the string are 
allowed only to separate digits into groups of four or eight. 
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Hexadecimal If a string is expressed in hex, place the letter X (uppercase or 
lowercase) immediately following the closing quote. Spaces within 
the string are allowed only to separate the digits into pairs. For 


example: 
say 37 /* displays '37' (decimal number) *] 
say "%" /* displays '%' (ASCII character 37) *) 
say '25'x /* '37' in hex; says '%' (ASCII 37) sf 


say '0010 0101'b /* '37' in binary; says '%' (ASCII 37) */ 


Note: If you use x or b as variables, REXX gives precedence to their use as 
number-base indicators. For example: 


x = 'mno' /* assign a string to variable X */ 
say '3F'x /* displays the character '?' +) 
/* ... not '3Fmno' */ 


Using Functions to Convert Data 
The following REXX built-in functions convert numbers from one form to another 
or convert character data to its numeric form. 


B2x0 Binary to hexadecimal 
C2X0 ASCII to hexadecimal 
C2D0 ASCII to decimal 

X2BO Hexadecimal to binary 
X2COQ Hexadecimal to ASCII 
X2D0 Hexadecimal to decimal 
D2CO Decimal to ASCII 
D2X0 Decimal to hexadecimal. 


The following function calls represent the conversions they perform. 


2 means translate to 

B means binary 

C means characters (that is, ASCII) 
X means hexadecimal. 

D means decimal. 


Thus the value of: 


B2X(0011 1111) is 3F 
X2B(3F) is 00111111 
C2X(?) is 3F 
X2C(3F) is ? 

C2D(?) is 63 

D2C(63) is ? 
D2X(63) is 3F 
X2D(3F) is 63. 


All these functions accept strings more than 1 byte long. 

Note: For some decimal or hexadecimal numbers, the ASCII character is different, 
depending on the code page that you are using (see Keyboard Layouts). 

Binary numbers can only be translated to and from hexadecimal numbers. To 
translate binary into other forms, use nesting. For example, the value of: 


X2C(B2X(0011 1111)) is ? 
X2B(D2X(63)) is OOLII111. 
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Figure 4-6 on page 4-21 shows a table of conversion functions. 


From 


Paine || KD 
aneXoD| ==; aK) | COD 
Tix | ame [acm |) 
xawpexey] Dacm | pix | __ 


Figure 4-6. Conversion Table 


For complete descriptions of these functions, refer to the REXX Reference. 
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Basics 


Environment 


Chapter 5. Commands 


Commands are instructions that REXX passes to another environment. You can use 
a program written in REXX to control other programs, including the operating 
system (OS/2 program) for your computer. 


If you use an application program, such as a word processor, that is controlled by 
subcommands (the application commands, typed at a user prompt), you can use 
REXX to create macros, programs that issue a series of subcommands to an 
application. You can, in effect, create your own commands. 


You may now be using the OS/2 Batch Facility to automate the OS/2 tasks. Using a 
REXX program instead, with its variables, its control structures, and its math and 
parsing capabilities, can make these procedures much more powerful. 


In this chapter: 


Basics 


Environment 
From REXX to the OS/2 Program 


From the OS/2 Program to REXX 
Trying out REXX Instructions. 


Environment is a term used to describe the workspace that the OS/2 program and 
certain applications create for themselves. You may already be familiar with the 
idea of an environment with respect to the OS/2 command set, which defines (or 
displays) various settings such as default paths and files. 


Using REXX, the term environment refers not so much to individual features of the 
OS/2 program or other applications, but rather to the way they operate generally. 
REXX does not impose an environment of its own. Instead, it operates entirely 
within the environment (default environment) from which it is called. This could be 
the environment of the OS/2 program or of any application program that can use 
REXX as a macro or scripting language. 


The basic rule is that whatever REXX cannot process, it evaluates and then passes 
the result to the default environment. 


The concept of environment becomes important when you use a REXX program to 
issue commands to other programs. Fortunately, the REXX language makes this 
easy. Starting your REXX programs from the OS/2 command line makes the OS/2 
program the default environment for REXX commands. 
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From REXX to the OS/2 Program 


There are three ways to issue a command to the OS/2 program. You can: 


e Let REXX evaluate part or all of a clause as an expression. The resulting string 
is automatically passed to the OS/2 program. 


¢ Enclose the entire clause in quotes. That renders it a literal string to be passed 
to the OS/2 program. 


e Send a command explicitly to the OS/2 program by using the ADDRESS 
instruction. 


issuing a Command Expression 
REXX processes your program one clause at a time. It examines each clause to 
determine if it is: 


e A keyword instruction, such as: 
say "Type total number" 
or 
pull input 
e A variable assignment (any valid symbol followed by an equal sign), such as: 
price = cost * 1.2 
e A label for calling other routines (see “Subroutines” on page 7-1) 
e A null (empty) clause. 


If the clause is none of the above, REXX evaluates the entire clause as an expression 
and passes the resulting string to the OS/2 program. 


If the string is a valid OS/2 command, then the OS/2 program processes it as though 
you had typed the string at the command prompt and pressed the Enter key. 


Figure 5-1 shows a REXX clause that uses the DIR command in the OS/2 program 
to display a list of files in the current directory. 


/* display current directory */ 
say "DIR command via REXX" 
dir 


Figure 5-1. DIRREX.CMD 


The clause dir is not a REXX instruction or a label, so REXX evaluates it and 
passes the resulting string to the OS/2 program. The OS/2 program recognizes the 
string DIR as one of its commands and processes it. This is also true if the PATH 
command is used to display the current search path for processible files (see 
Figure 5-2). 


/* display current path ff 


say "PATH command via REXX" 
path 


Figure 5-2. PATHREX.CMD 
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REXX evaluates the clause path and passes the string PATH to the OS/2 program as 
a command. 


Figure 5-3 shows a program using the DIR and PATH commands. The PAUSE 
command is added to wait for the user to press a key before issuing the next 
instruction or command. Also, borders were added. 


/* Issue DIR and PATH commands to 0S/2 


say copies('=',40) /* display line of "="'s 
/* for a border 


dir /* display listing of 
/* the current directory 


/* pauses processing and 
/* tells user to "Press 
/* any key to continue." 


say copies('=',40) /* display line of '=' 
path /* display the current 
/* PATH setting 


Figure 5-3. DP.CMD 


The following is displayed on the screen when you run the program. 


[c:\]dp 


ee ce or cre ee wae re ee ors a er ee 
SSS SS SS SS SS SS SS SS SS SS SS SS SS SS SS 


The volume label in drive C is 0S2. 
Directory of C:\EXAMPLES 


<DIR> 10-16-88 12:43p 
<DIR> 10-16-88 12:43p 


EX4 1 CMD nnnn 10-16-88 1:08p 
DEMO TXT 117. 10-16-88 1:10p 

4 File(s) 12163072 bytes free 
Press any key when ready... 


PATH=C:\0S23C:\0S2\UTIL;C:\0S2\ INSTALL 
[C:\] 


Echoing of OS/2 Commands: 
When your REXX program issues an OS/2 command, REXX passes the command 
to the OS/2 command handler for processing. This processing includes displaying 
the command on the screen (echoing). Commands are also echoed in old-style 
(non-REXX) .CMD files. 


This echo can be distracting. To suppress it, issue the ECHO OFF command from 
your REXX program. This tells the OS/2 program to suppress all echoing for the 
remainder of your REXX program. To suppress echoing for one command, put an 
at sign (@) in front of the command. 


Note: For simplification, the examples in this book do not echo commands. 
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Issuing a Command to Call a .CMD File 


Using Variables 


If you are issuing a command to have the OS/2 program run one of its built-in 


commands or other programs, you can call it by name as previously shown. 


However, to have the OS/2 program run another .CMD program from your REXX 
program, you must call it using a CALL instruction instead of calling it by name. 
There are two kinds of calls you can use: 


¢ The REXX CALL instruction 
e The OS/2 CALL command. 


The REXX CALL instruction calls other REXX programs. To call a REXX 
program named mysub1, you could write the CALL instruction, cal] mysubl. 
REXX recognizes the CALL instruction, handles the call, and processes mysub1 as a 
REXX program. 


The REXX CALL instruction does not work to call a non-REXX .CMD file. 
Instead, you would use the OS/2 CALL command. To call a non-REXX .CMD 
program named mysub2, you could write the CALL instruction, "call mysub2". 
REXX evaluates the expression and passes it to the OS/2 command handler for 
processing. The command handler recognizes the CALL command and processes 
mysub2 as a .CMD program. 


The quotation marks around call mysub2 indicate that this is the OS/2 CALL 
command instead of a REXX CALL instruction. 


Figure 5-4 shows a program that builds a command string using a variable for user 
input. It prompts the user to type a file name and then builds a variable to hold the 
TYPE command and the input file name. 


To have REXX issue the command to the operating system, put the command string 
on a line by itself. REXX evaluates the string and tries to issue it as a command, 
which is passed to the OS/2 program. 


/* Issue TYPE command with an input file name */ 


/* prompt the user for a file name tf 
say "Type a file name:" 


/* assign the response to variable FILENAME 
pull filename 


/* build a command string by concatenation 
commandstr = "TYPE" filename 


/* If the user typed "demo.txt": 
/* Now the variable COMMANDSTR contains 
/* the string "TYPE DEMO.TXT" and so... 


commandstr /* ...REXX passes the 
/* string on to 0S/2 


Figure 5-4. SHOFIL.CMD 
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Using Quotes 


The following is displayed on the screen when you run the program. 


[C:\]shofil 
Type a file name: 
demo. txt 


This is a sample text file. Its sole 


purpose is to demonstrate how 0S/2 
commands can be issued from REXX 
programs . 


[C:\] 


The rules for forming a command from an expression are exactly the same as those 
for forming expressions. Be careful of symbols that have meanings for both REXX 
and OS/2 programs. To determine how REXX evaluates a command when the 
command name and a variable name are the same, use the program DIRREX.CMD 
(see Figure 5-1 on page 5-2) and assign a value to the symbol DIR as shown in 
Figure 5-5. 


/* assign a value to the symbol DIR */ 
say "DIR command via REXX" 
dir = “echo This is not a directory!" 


/* pass the evaluated variable to 0S/2 */ 
dir 


Figure 5-5. DIRREX2.CMD 


Now dir is a variable with the string, “echo This is not a directory!", as the 
assigned value. 


The following is displayed on the screen when you run the program. 


[C:\]Jdirrex2 
DIR command via REXX: 


This is not a directory! 


[c:\] 
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To Summarize 


REXX evaluates a literal string, a string enclosed in matching quotes, exactly as it is 
found. To ensure that a symbol in a command is not evaluated as a variable, 
enclose it in matching quotes as shown in Figure 5-6. 


/* assign a value to the symbol DIR */ 
say "DIR command via REXX" 
dir = "echo This is another string now!" 


/* pass the literal string "dir" to 0S/2 * / 
"dir" 


Figure 5-6. DIRREX3.CMD 
The result displayed on the screen is now a directory listing. 


The best way to ensure that REXX passes a string to the OS/2 program as a 
command is to enclose the entire clause in quotes. This is especially important when 
you use OS/2 symbols that REXX uses as operators. 


If you were trying to erase a set of files by wildcard pattern, the clause, 

delete *.bak, would result in a syntax error. REXX would read the * as its 
multiplication operator, and REXX would try to multiple the value of “delete” by 
the value of “.bak”. Those values are not numbers; therefore, the multiplication 
would fail. 


The same thing happens with the character /. It denotes command options in the 
OS/2 program, but to REXX, it is the division operator: 


w = "anything" 

dir/w 

This would also result in a syntax error, because you can only divide with numbers. 
The correct way would be: 

delete "*. bak" 

dir" /w" 

or 

"delete *.bak" 

u di r /w u 

If you want to use a variable in the command string (see Figure 5-4 on page 5-4), 
leave the variable outside the quotes. For example: 

extension = "BAK" 

"delete *."!lextension 


option = "/w" 
"dir"| loption 


The basic points of using commands are: 
¢ REXX always examines each clause for REXX syntax. 


¢ If REXX finds no valid instruction or label and the clause is not empty, then it 
evaluates the clause as an expression. 
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e The result of the expression, a string, is then passed on to the environment from 
which REXX was originally called—the default environment. 


ADDRESS Instruction 


Test Yourself 


A more explicit way to send a command to the environment is by using the 
ADDRESS instruction, ADDRESS environment expression, where: 


environment is the destination of the string. To address the OS/2 program, use the 
symbol CMD. 


expression is evaluated by REXX as a string to be passed to the environment. 


The ADDRESS instruction works like this: 


address CMD "dir" /* pass the literal string */ 
/* "dir" to the 0S/2 program */ 


cmdstr = 'dir *.txt' /* assign a string a} 
/* to a variable */ 
address CMD cmdstr /* REXX passes the string af 


/* "dir *.txt" to the 0S/2 program */ 


When you use the ADDRESS instruction this way, REXX first evaluates the string 
expression that follows the CMD. Then, it sends the resulting string to the OS/2 
program. 


The ADDRESS instruction in this example works exactly the same way as in the 
methods already described. If you want to send a literal string to the OS/2 program, 
you must enclose it in quotes. Otherwise, REXX evaluates the terms and operators 
and passes the resulting string to the OS/2 program. 


The ADDRESS instruction lets a single REXX program issue commands to two or 
more environments. This can be used when using REXX as a macro language. 


Figure 5-7 shows a program that passes the DIR command and SORT filter to the 
OS/2 program. 


* 


say 'Type fragment’ 
pull frag 


if frag = '' then 
say ‘You asked for it!’ 
'DIR' frag }{'*.* {| SORT' 


Figure 5-7. FILFRAG.CMD 


1. What does each line of the program do? 

2. What happens if the user types who at the prompt message? 

3. What happens if the user presses the Enter key without typing anything? 
4. What happens if no files fit the pattern? 
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Answers: 


1. Here is what the program does: 
¢ The first line is a comment. 


¢ The second line displays the prompt message, Type fragment:, on the 
screen. 


¢ The third line reads the user’s entry and stores it in the variable frag. 


e The fourth line tests if frag is empty, as in HELLO.CMD, see Figure 2-1 
on page 2-1. 


¢ If frag is empty, then the fifth line displays the message, You asked for it!, 
on the screen. 


¢ The sixth line is evaluated as a string expression and concatenates the 
contents of frag into a DIR command with a wildcard file-pattern. The 
directory is sorted and displayed on screen. 


2. The OS/2 program displays a directory for the command 
DIR WHO*.* | SORT 


3. The program displays the message You asked for it! and then a listing of all 
files in the current directory, as if the command DIR *.* | SORT had been typed. 


4. The OS/2 program displays the message, The system cannot find the file 
specified., on the screen. 


The following is displayed on screen when you run the program. 


[C:\]filfrag 
Type fragment 


who 
<sorted directory display> 


[C:\] 


The following is displayed on the screen if you make no entry and press the Enter 
key. 


5-8 REXX User’s Guide 


[C:\]filfrag 
Type fragment 


You asked for it! 
< full directory listing > 


[c:\] 


The following is displayed on the screen if no files in the current directory match the 
given pattern. 


[C:\]filfrag 
Type fragment 
who 


SYS0002 The system cannot find the file specified. 


From the OS/2 Program to REXX 
Information between REXX and OS/2 programs is passed both ways; this is an 
essential part of using REXX with other environments. If a command fails to 
operate the way you intended, such as if you try to copy a file that does not exist, 
you get a message that tells you that file cannot be found and you can respond 
accordingly. 


The same thing happens when a REXX program tries to copy a nonexistent file, 
except that for REXX to respond, it must be apparent that a system error has 
occurred. Otherwise, the program continues running, unaware that neither the 
source file nor the copy of it exists. 


A system error alone does not stop the running of a REXX program. Without some 
provision to stop the program, called a trap, REXX continues running. You may 
have to press the Control (Ctrl)+Break keys to stop processing. 


With each command it processes, the OS/2 program produces a number called a 
return code. When a REXX program is running, this return code is automatically 
assigned to a special built-in REXX variable named RC. 


If the command was processed with no problems, the return code is nearly always 0. 
If something goes wrong, the return code issued is another nonzero number, 
depending on the command itself and the error encountered. 


In the previous example, the file not found error occurred at the end of the program, 
so there was no great problem. But a system error that occurs in the middle of a 
program can indeed cause trouble. 


-Reading Return Codes 
Figure 5-8 shows a program that can read a return code. 


/* RC report */ 


"TYPE nosuch. fil" 
say "the return code is" RC 


Figure 5-8. GETRC.CMD 
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Figure 5-9 shows a program that displays a response to the return code. 


/* Simple if/then error-handler. */ 
say "Type a file name:" 
pull filename 


"TYPE" filename 
if RC \= 0 
then say "Could not find" filename 


Figure 5-9. REPORTRC.CMD 


This program tells you only that the OS/2 program could not copy a nonexistent file. 
This program does not do much more than the OS/2 program does, but you have 
the basic idea of how to capture a return code. 


Programs need to respond more effectively to whatever situation occurs. This 
applies not only to OS/2 errors, but also to the choices of a program user and even 
the data that the program processes. For that kind of response, REXX has 
instructions, such as IF, that control the processing of the program itself, sometimes 
called its flow. For more information about program flow, refer to Chapter 6, 
“Program Control.” 


More and Better Traps 
When you have completed “Basics” in this guide, you may want to explore other 
methods of controlling system errors, particularly the instructions: 


¢ CALL ON ERROR 

¢ CALL ON FAILURE 

¢ SIGNAL ON ERROR 

¢ SIGNAL ON FAILURE. 


These instructions are discussed in “Advanced Topics” in this chapter (see “Trapping 
Command Errors” on page 5-14) and “Instructions” in the REXX Reference. 


The REXXTRY Program 
REXXTRY is a REXX command that lets you run different REXX instructions 
and observe the results. REXXTRY is also useful when you want to do a REXX 
operation only once, since it is easier than creating, running, and erasing a .CMD 
file. REXXTRY can be used as a learning tool. It allows you to experiment with 
different REXX instructions and observe the results. As with other REXX 
programs, REXXTRY may be run in full screen or in a window. 


Beginning and ending a REXXTRY session is easy. To start a REXXTRY session 
type the following: 

REXXTRY 
To end a REXXTRY session, type: 

EXIT or RETURN 


+] 


Here are some examples of how to use the REXXTRY command: 
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REXXTRY say 1+2 /* Displays 3 


REXXTRY say 2+3; say 3+4 /* Displays 3 
/* Displays 4 


REXXTRY sum = 1+2+3+4; say ‘average is' sum/4 /* Displays 2.5 


Figure 5-10. REXXTRY Example 


Note that when you run REXXTRY from a command line and provide some REXX 
instructions on that command line, the OS/2 command interpreter processes the 
command line in its usual way. That means it may treat part of your input in a way 
you do not expect. For instance, if you type: 


REXXTRY Say AB>CD 


the REXXTRY program is not run with the argument “Say AB>CD.” Instead, it is 
run with the argument “Say AB,” and the output of the program will be redirected to 
the file CD. This is because the OS/2 command interpreter recognizes the > 
character as a redirection operator. 


However, when you start REXXTRY without a parameter and then enter an 
instruction, for example, Say AB > CD, REXX processes the instruction directly. 
REXXTRY performs the comparison between AB and CD and writes the result, ’0.” 


Figure 5-11 shows how to run REXXTRY interactively. 


fic: \"rexxtry 
REXXTRY.CMD lets you interactively try REXX statements. 
Each string is executed when you hit Enter. 
Enter 'call tell' for a description of the features. 
Go on - try a few... Enter ‘'exit' to end. 
say AB > CD 


0 
ceeeee ec ecceees eecone Peree eT eee er eT ee REXXTRY.CMD on 0S/2 


sum=1+2+3+4 
REXXTRY.CMD on 0S/2 
say ‘average is' sum / 4 


average is 2.5 


wodateiceswae et eees cocoons eeseeeeee REXXTRY.CMD on 0S/2 


exit 


fic :\" 


Figure 5-11. REXXTRY Interactive Example 
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Summary 
This completes “Basics” in this chapter. You have learned how to: 


¢ Pass commands from REXX programs to the OS/2 program: 
— Using expressions 
— Using the ADDRESS instruction. 
¢ Read the RC variable that the OS/2 program returns to REXX 
¢ Run REXX< instructions by using the REXXTRY command. 


“Advanced Topics” in this chapter discusses: 


Using REXX as a substitute for batch files 

Using REXX as a macro language 

Using SIGNAL and CALL to trap errors and failures 
Using PMREXX to run programs. 


To continue with “Basics,” go to page 6-1. 
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Advanced Topics 


In this chapter: 


Advanced Topics 


REXX and Batch Files 
Subcommand processing 


Trapping command errors 
Running REXX programs in a window. 


REXX and Batch Files 


You can use a REXX program anywhere you now use OS/2 batch files. Figure 5-12 
shows an example of an OS/2 batch file that processes user input to display a help 
message. 


@echo 


if %1. 


if %1 
if %1 
if %1 
if %1 
if %1 
if %1 
if %1 
if %1 
if %1 
if %1 
if %1 


if %1 
helpmsg %1 
goto exit 


:msg 


off 


helpmsg 
goto exit 


syes 


- goto msg 
on goto yes 
off goto no 
ON goto yes 
OFF goto no 
On goto yes 
ON goto yes 
OFf goto 
OfF goto 
Off goto 
oFF goto 
oFf goto 
ofF goto 


prompt $i[$p] 
goto exit 


:no 
cls 


prompt 


sexit 


Figure 5-12. HELP.CMD (OS/2-batch version) 
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Figure 5-13 shows an example of an equivalent program in REXX. 


/* HELP.CMD - Get help for a system message */ 
arg action . 
select 
when action='' then "helpmsg' 
when action='0N' then ‘prompt $i[$p]' 
when action='OFF' then do 


"cls! 
‘prompt ' 
end 
otherwise 'helpmsg' action 
end 
exit 


Figure 5-13. HELP.CMD (REXX version) 


Subcommand Processing 
REXX programs can issue commands or subcommands to programs other than the 
OS/2 program. The specifics about other application environments are beyond the 
scope of this book. However: 


¢ If your application permits access to the OS/2 system prompt, you can call 
REXX programs that way. 


¢ To use REXX as a macro or scripting language in applications such as word 
processors, the application must be registered with the language processor. This 
is done by the producer of the program. 


¢ If you have programs of your own that you want to register with the language 
processor, refer to “Applications Programming Interfaces” in the REXX 
Reference. 


Trapping Command Errors 
The most efficient way to detect errors from commands is by creating condition 
traps, using the SIGNAL ON and CALL ON instructions, with either the ERROR 
or the FAILURE condition. When used in a program, these instructions enable 
(switch on) a detector in REXX that tests the result of every command. Then, if a 
command signals an error, REXX stops normal program processing, searches the 
program for the appropriate label (ERROR: or FAILURE:) or a label that you created, 
and resumes processing there. 


The SIGNAL ON and CALL ON instructions also tell REXX to store the line 
number (in the REXX program) of the command instruction that triggered the 
condition. That line number is assigned to the special variable SIGL. Your 
program can get even more information about what caused the command error 
through the built-in function CONDITIONO. 


Using the SIGNAL and CALL instructions to handle errors has several advantages. 
Programs: 


e Are easier to read, because you can confine error-trapping to a single, common 
routine 
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e Are more flexible, because they can respond to errors by clause (SIGL), by 
return code (RC), or by other information (CONDITION(O) 


e Can catch problems and react to them before the environment issues an error 
message 


e Are easier to correct, because you can turn the traps on and off (SIGNAL OFF 
and CALL OFF). 


For other conditions that may be detected using SIGNAL ON and CALL ON, see 
“Condition Traps” on page 7-15. 


instructions and Conditions 


Disabling Traps 


The instructions to set a trap for errors are: 


SIGNAL ON condition [NAME trapname] 
CALL ON condition [NAME trapname] 


SIGNAL ON Initiates an exit subroutine that ends the program 


CALL ON Initiates a return subroutine that returns processing to the clause 
immediately following the CALL ON instruction. Use this 
instruction to recover from a command error or failure. 


The two command conditions that can be trapped are: 


ERROR Detects any nonzero error code issued by the default environment 
as the result of a REXX command 

FAILURE Detects a severe error preventing the system from processing the 
command. . 


A failure, in this sense, is a particular category of error. If you use SIGNAL ON or 
CALL ON to set a trap only for ERROR conditions, then it traps failures as well as 
other errors. If you also specify a FAILURE condition, then the ERROR trap 
ignores failures. 


As an option, you can also use the NAME keyword to specify a particular subroutine, 
trapname, to be run. When an ERROR or FAILURE condition occurs and: 


¢ Ifa trap is specified by name, REXX jumps to the clause following the 
appropriate label (the trapname followed by colon). 


e If you do not specify a trapname in the SIGNAL ON or CALL ON instruction, 
REXX searches for a label matching the appropriate condition. It looks for the 
label ERROR: or FAILURE:). 


For more information about other conditions that can be trapped, see “Condition 
Traps” on page 7-15. For more information about how labels are used to call 
subroutines, refer to Chapter 7, “Program Structure.” 


To turn off a trap for any part of a program, use the same instruction with the OFF 
keyword, such as: 

SIGNAL OFF ERROR 

SIGNAL OFF FAILURE 


CALL OFF ERROR 
CALL OFF FAILURE 
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Using SIGNAL ON ERROR 
Figure 5-14 shows an example of how a program might use SIGNAL ON to trap a 
command error in a program that copies a file. In this example, an error occurs 
because a nonexistent file name is stored in the variable FILE]. Processing jumps to 
the clause following the label error:. 


/* example of error trap */ 
signal on error /* Set the trap */ 


"COPY" filel file2 /* When an error occurs... */ 


exit . 

error: /* ..»REXX jumps to here */ 
say "Error" rc “at line" sig] 

say "Program can not continue." 

exit /* and ends the program. */ 


Figure 5-14. SIGNAL ON Trap 


Using CALL ON ERROR 
If there were a way to recover, such as by typing another file name, you could use 
CALL ON as shown in Figure 5-15 to recover and resume processing. 


/* example of error recovery */ 
call on error 


"COPY" filel file2 
say "Using" file2 


exit 
error: 
say "Can not find" filel 
say "Type Y to continue anyway." 
pull ans 
if ans = "Y" then 
do 


/* create dummy file */ 


file2 = "dummy. fil" 
RETURN 
end 

else exit 


Figure 5-15. CALL ON Trap 
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A Common Error-handling Routine 


Using PMREXX 


Figure 5-16 shows an example of a simple error trap that can be used in many 
programs. 


/* Here is a sample “main program" * 


signal on error /* enable error handling */ 
‘ersae myfiles.*' /* mis-typed 'erase' instruction aid 
exit 


/* And here is a fairly generic error-handler for this */ 


/* program (and many others...) */ 
error: 
say ‘error’ rc ‘in system call.’ 
say 
say 'line number = 
say ‘instruction = ' |} sourceline(sig1) 
exit 


sigl 
i 


Figure 5-16. SIGERR.CMD 


Earlier you learned to run REXX programs from the OS/2 command line. You can 
also run REXX programs with the PMREXX command. The PMREXX command 


runs a REXX program in a Presentation Manager window. The Presentation 
Manager window gives you: 


e A window for REXX output from: 
— The SAY instruction 
— Output and error messages from OS/2 commands 
— REXX TRACE output. 
e An input window for: 
— The PULL and PARSE PULL instructions 
— Input to OS/2 programs and commands 
¢ REXX output browsing, scrolling, and clipboard capability 
e A selection of fonts for the output window 
¢ Menu options to trace or end a REXX program. 


Starting the PMREXX Program 


Using PMREXX to run a REXX program is easy. Just add the command 
“PMREXX” to the front of your command line: 


PMREXX rexxtry say "Hello Stranger!" 


PMREXX displays "Hello Stranger!" in a Presentation Manager window, then 


displays a Presentation Manager message box to inform you that the REXX 
program has ended. 


Figure Figure 5-17 on page 5-18 shows a simple REXX program for displaying 


OS/2 files. 
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#R* 
‘@echo off' 


Do Forever 
Say 'Please enter a file or directory name' 


Parse Pull filename 
If filename = '' 
Then Leave 
‘dir' filename 
End 


Figure 5-17. FILES.CMD 


Run the program FILES.CMD and type the following response when the program 
pauses: 


C:\0S2 


There are very many files in the C:\OS2 directory, more lines that will fit in an OS/2 
command window. The first files in the list will scroll off the top of the screen 
before FILES.CMD pauses again. Press enter one more to end the program, then 
type in the command: 


pmrexx files 


PMREXX will display the prompt from FILES.CMD in the PMREXX window and 
pause until you type in a file name. You must type the file name in the input box at 
the top of the PMREXX window. Again, type the response 


C:\0S2 


When the FILES.CMD pauses again, you can use the PMREXX window scroll bars 
to see the first lines the DIR command displayed. You can move or size the 
PMREXX.EXE window or select PMREXX menu-bar choices: 


Menu-Bar Choice Description 
File Save the PMREXX output or exit PMREXX 
Edit Copy to the clipboard, paste the clipboard to the input 


box, clear the PMREXX output window, and select all 
lines in the PMREXX output window. 


Options Restart the REXX program, turn on REXX interactive 
Trace, and change the PMREXX output window font. 


Actions Halt the REXX program, trace next REXX instruction, 
redo the last REXX instruction, and turn off REXX 
tracing. 

Help PMREXX help. 


The RxMessageBox Function | 
When you run your REXX programs with PMREXX, you can also use the 
RxMessageBox function to display messages. For example, you can use 
RxMessageBox to display an error message: 
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/* Check the input parameter */ 
arg count 
if datatype(count, 'Whole') < > 0 then do 


RxMessageBox("Argument" count “is not a whole number") 
exit 
end 


Figure 5-18. ERROR.CMD 


RxMessageBox displays a Presentation Manager message box with a title of “Error!” 
and an “OK” button. The REXX program will wait until you press the “OK” 
button. 


You can change message box title and buttons. You can also add a colorful icon to 
the message box: 


/* Does the file exist? */ 
if stream(file, 'Command', “Query Exists") <> '' 
then do 


reply = RxMessageBox("Do you want to replace file" file"",, 
"Replace File?", "YesNo", “Question") 
if reply = 7 then exit /* user pressed 'No' */ 
end 


Figure 5-19. FILECHK.CMD 


FILECHK.CMD displays a question in a message box with a question mark icon 
and two buttons; one labeled “Yes,” the other labeled “No.” When you press the 
Yes or No button, gives your program the number of the button you chose. The 
Yes button is number 6 and the No button is number 7. 


The PMREXX Trace Option 
The PMREXX /T option turns on interactive tracing for the REXX program. You 
must place the /T option before the name of the REXX program name: 


PMREXX /T files 
You can use the PMREXX menu to control how REXX traces the program. 


With PMREXX you can also turn tracing on while a program is running. Select 
Interactive trace from the Options menu to do this. 


Chapter 5. Commands 5-19 


5-20 REXX User’s Guide 


Chapter 6. Program Control 


So far, the sample programs have been fairly straightforward lists of clauses. 
Various instructions have been used to input, store, display, and manipulate 
information. 


In this chapter, another class of instructions, keywords that manipulate the program 
itself, are discussed. One of these, IF... THEN... ELSE, was already used to choose 
between two possible directions a program might take. 


Basics 
In this chapter: 


Basics 


Changing the flow of a program 
Repetitive tasks 


Conditional loops 
Using counters to exit loops 
Exiting a program. 


Changing the Flow of a Program 
A program can be: 


e A single list of instructions 


e A number of short lists connected by instructions that determine which list to 
process and how many times to process it. 


Instructions that direct the processing of the program are called control instructions. 
The maneuvers they perform include: 


Branching Selecting one of several lists of instructions to process. The 
branching instructions are IF and SELECT. 


Looping Repeating a list of instructions, either for a specified number of 
times or as long as some condition is satisfied. The DO instruction 
(when used with keywords like UNTIL and WHILE) does the 
looping in REXX. 


Exiting A program that is a single list ends when it reaches the last 
instruction. To explicitly end a program, use the instructions EXIT 
and RETURN. 


Grouping Instructions 
What most control instructions have in common is that they often use groups of 
clauses that act as a single clause. The simplest way to group clauses is with the 
keyword DO. For example: 


DO 
clausel 
clause2 
clause3 


END 
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Testing Conditions 


Simple Branching 


If the keyword DO is in a clause by itself, the list of clauses that follows (up to the 
END keyword) is processed once (no loop is implied). This form of the DO 
instruction and the END keyword associated with it tell REXX to treat the enclosed 
instructions as a single instruction. 


The enclosed instructions may be indented to the right. The indentation does not 
affect how REXX processes the list. It does, however, make the program easier for 
people to read. It shows that these instructions belong together. 


In Chapter 4, “Expressions,” a class of expressions called comparisons, which test 
whether a given condition is true or false, was introduced. In a comparison, two 
terms are joined by operators such as = (equal to), > (greater than), or < (less 
than) in order to pose a test of the terms. The expression itself evaluates as, 1 if the 
comparison is true or 0 if the comparison is false. For example: 


/* some comparisons */ 


say 5=5 /* displays '1' - true *] 
say 5 <4 /* displays '0' - false */ 
say 5 =4 /* displays '0' - false */ 
say 5 >4 /* displays '1' - true */ 
reply = "YES" /* assigns the string "YES" 
to the variable REPLY */ 
say reply /* displays "YES" ai f 
say reply = "MAYBE" /* displays '0' - false */ 
say reply = "YES" /* displays '1' - true */ 


For more complex ways to combine terms and operators to form comparisons, see 
“Comparisons” on page 4-13. 


To tell REXX how to make a decision about a single instruction, use: 


IF expression 
THEN instruction 


REXX processes instruction only if expression is true, see Figure 6-1. 


/* Asking confirmation */ 
say "Type YES to continue" 


pull reply 
if reply = "YES" then say "OK!" 
/* program continues from here...*/ 


Figure 6-1. CONFIRM.CMD 


The instruction say "OK!" is processed only if the variable reply has the value YES. 
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The IF instruction introduces a new branch of instructions to process when the IF 
expression is true. Programmers often visualize the action of a decision-making 
instruction by using a diagram like this, called a flowchart. 


Say “OK” 


The decision-making expression is represented by a diamond. If the expression (here 
REPLY="YES") evaluates as true, then the program branches, or takes a detour, 
through one additional instruction before resuming on the next line. 


Using DO...END for Multiple Clauses : 
To put a list of instructions after the THEN, use the DO instruction and the END 
keyword. That turns the whole group into a single instruction. For example: 


IF expression THEN 
DO 
instructionl 
instruction2 
instruction3 
<...and so on> 
END 


With the DO and END keywords bracketing the list, REXX knows to treat the 
listed instructions as a unit to: 


e Process all of them if expression is true 
e Ignore them all if expression is false. 
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Figure 6-2 shows an example using DO and END. 


/* Wake-up call */ 
if sun = "shining" 
then 

do 


say "Get up!" 

say "Get out!" 

say "Meet the sun half way!" 
end 


Figure 6-2. WAKEUP.CMD 


The flowchart diagram would look like this. 


DO 
SAY "Get up” 
SAY “Get out” 

SAY "meet the sun” 
END 


In the previous example, if sun = "shining" evaluates as 1 (true), then all three SAY 
instructions are processed. But if sun = "shining" evaluates as 0 (false), then none 
of the SAY instructions are processed. 


The THEN and DO keywords are each on a separate line. This is optional. You 
could also write the program as: 


/* ...this way... */ /* ...or this way */ 
if sun = "shining" then If sun = "shining" then do 
do say “Get up!" 

say “Get up!" (etc.) 

(etc.) end 

end 


Test Yourself 
Refer to Figure 6-2. What would happen if you left out DO and END keywords? 


Answer: Without DO and END to mark the list as a unit, REXX assumes that 
only the first instruction following THEN is processed on condition. 


The instruction, say "Get up!", would be processed only if the comparison 
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Two Paths: ELSE 


expression, sun = "shining", is true. The rest of the instructions in the list would 
always be processed, regardless of the true\or-false condition of expression. 


Used alone, IF...THEN adds a branch of instructions to process when the 
controlling expression is true. You can also add a second branch of instructions to 
process when the expression is false. The keyword ELSE introduces this alternate 
list. For example: 


IF expression 
THEN instructionl 
ELSE instruction2 


When IF is used this way, REXX processes only one of these instructions, not the 
other. It will process: 

e Instructionl only if expression is true 

e Instruction2 only if expression is false. 


IF, THEN, and ELSE were used to control the processing of the first program in 
this book, HELLO.CMD, as shown in Figure 6-3. 


/* A conversation */ 
say "Hello! What is your name?" 


pull who 
if who = "" then say "Hello stranger" 
else say "Hello" who 


Figure 6-3. HELLO.CMD 


The flowchart diagram would look like this. 


"Hello stranger!” 


A 
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The same idea, with a command, is used to create a more practical program. 

Figure 6-4 shows a program that takes a file name and creates a backup copy. You 
may want to compare the program shown in Figure 6-4 to the REPORTRC.CMD 
program shown in Figure 5-9 on page 5-10. 


/* backup a REXX program */ 

arg fname". "ext /* This is a technique called 
"parsing a literal pattern". 
Use it just as you see it 
here for now; more about it 
on page 8-10. 


if fname = "" then do If no file name typed, then 
Say "Type a file name:" prompt user to type a name 
pull fname"."ext 
end 


if ext = "" then ext = "CMD" IF no extension given, then 
give it the extension '.CMD' 


"dir" fname". "ext displays directory entry for 
the input file name, thereby 
making sure it exists.... 


if rc < 0 then do /* IF no such file exists, then 
say "No backup performed." EXIT the program. (More about 
say "Program ended." the EXIT instruction on 
exit on page 6-23.) 
end 


else do /* ELSE, copy the file to 
say "Backing up" fname". "ext /* one with the extension */ 
"copy" fname"."ext fname".BKP" /* '.BKP'; then confirm */ 
"dir" fname". BKP" /* it with a "DIR" command */ 
say "Program ended" 
exit 
end 


Figure 6-4. BACKITUP.CMD 


The ELSE clause must also use DO and END to bracket a list of instructions. 
Note: REXX features in this program that have not been introduced yet are: 
¢ The EXIT instruction, which tells REXX explicitly to end the program. 


¢ The period in quotes in the ARG and PULL instructions called a literal parsing 
pattern, which tells REXX to remove that quoted string (if it occurs) in the 
user’s file name entry. What is left is broken into two parts, which in turn are 
assigned to the variable FNAME and EXT. This is the only example of a literal 
pattern used in “Basics”. For more information, refer to “Parsing with 
Patterns” on page 8-10. 
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The SELECT Instruction 
You are not limited to two choices. You can use the SELECT instruction to have a 
REXX program select one of any number of branches. For example: 


SELECT 
WHEN expressionl THEN instructionl 
WHEN expression2 THEN instruction2 
WHEN expression3 THEN instruction3 


OTHERWISE 
instruction 
instruction 
instruction 


END 


e If expressionl is true, instruction1 is processed. After this, processing 
continues with the instruction following the END. 


e If expression] is false, then expression2 is tested. If it is true, then 
instruction2 is processed and processing continues with the instruction 
following the END. 


e If expression, expression2, and so on, are all false, then processing continues 
with the instruction following the OTHERWISE. 


OTHERWISE is essentially the SELECT-equivalent of ELSE. If there is any 
possibility that all the WHEN expressions could be false, there must be an 
OTHERWISE clause. 
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The following is how SELECT is diagramed in a flowchart. 


SELECT 


THEN 


WHEN 


expression1 


WHEN 


expression2 


WHEN 


expression3 


OTHERWISE 


instruction(s) 


END 


To process a list of instructions following the THEN keyword, use: 


DO 
instructionl 
instruction2 
instruction3 


END 


A DO; ... END group is not required after the OTHERWISE keyword. 
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Multiple Choice 
Figure 6-5 shows a short program that uses SELECT. 


/* displays date/time information */ 


arg request /* get argument; convert to uppercase */ 


select 
when request 
when request 
when request 
t 
t 


"DATE" then say date() 

"TIME" then say time() 

"DAY" then say date(w) 

"MONTH" then say date(m) 

"SOFAR" then do 
say time(h) "hours" 
say time(m) "minutes" 
say time(s) "seconds" 

end 


when reques 
when reques 


/* if no valid argument given, display help information */ 


otherwise say "Valid arguments are:" 
say "date - calendar date" 
say "time - military time" 
say " day day of the week" 
say " month month" 
say " sofar hrs/min/sec since midnight" 


Figure 6-5. Q.CMD 


Remember that SELECT must have a corresponding END. As with DO, it makes 
your program easier for people to read if you indent everything between the 
SELECT and the END three spaces to the right. SELECT is a specialized form of 
the IF instruction. 


Test Yourself 
Write a program that asks the user to type two words on the same line and 
computes if: 


e The values of the words are the same (or numerically equal). 
e The value of the first word is higher. 
e The value of the second word is higher. 


The comparison must ignore differences in case. For example, A should evaluate as 
equal to a. 
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Answers: Figure 6-6 shows one possible program. 


/* This program requests the user to supply two 
/* words and says which is higher. 


say "Type two words" 
pull wordl word2 . 
select 
when word1 = word2 then 
say "The words are the same”, 
“or numerically equal” 
when wordl > word2 then 
say "The first word is higher" 
otherwise 
say "The second word is higher" 
end 


Figure 6-6. COMPAREI.CMD 


Notice that a period appears after the PULL instruction in Figure 6-6. You’ve 
already learned about using a period in compound symbols. (See “Using Compound 
Symbols” on page 3-8.) You can use a period as a placeholder with the PULL 
instruction. Refer to “Using a Placeholder” on page 8-7 for additional information. 


Figure 6-7 shows an alternative program using IF. 


/* This program requests the user to supply two 
/* words and says which is higher. 


say "Type two words" 
pull wordi word2 . 
if word1 = word2 


then say "The words are the same", 
“or numerically equal" 


else do 
if wordl > word2 
then say "The first word is higher" 
else say "The second word is higher" 
end 


Figure 6-7. COMPARE2.CMD 


Some people may consider the first solution better because it is slightly easier to 
understand. 


For other considerations about when to use IF and SELECT, see “Nested IF and 
SELECT” on page 6-26. 
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Repetitive Tasks 


Computers excel at repetitive tasks. An essential part of any computer language is a 
loop instruction, which is a way to make a program repeat a list of instructions: 


A specific number of times 

As long as some condition is true 
Until some condition is satisfied 
Forever (until the user wants to stop). 


To repeat a loop a number of times, use: 


DO exprr 
instructionl 
instruction2 
instruction3 


END 
where: 


exprr (the expression for repetitor) gives a whole number, which is the number 
of times the loop is processed. 


To make your program easier for people to read, you should indent the instructions 
between the DO and the END three spaces to the right. 


Figure 6-8 is an example of a repetitive loop that prints three documents five times. 


/* To print documents for a meeting: for each person, */ 
/* the agenda, minutes and accounts are printed once */ 


do 5 
"PRINT AGENDA.DOC" 
"PRINT MINUTES .DOC" 
"PRINT ACCOUNTS .DOC" 


Figure 6-8. HANDOUTS.CMD 


Consider how you would write a program that would ask for the number of copies 
needed and one that would ask for the names of the documents. 
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Figure 6-9 is an example of a repetitive loop that processes the instruction between 
the DO and the END, height times. 


/* The user is asked to specify the height of a 
/* rectangle (within certain limits). The rectangle 
/* is then displayed on the screen. 


say "Type the height of the rectangle", 
" (a whole number between 3 and 15)." 
pull height 
select 
when \datatype(height WHOLE) then say "Rubbish!" 
when height < 3 then say "Too small!” 
when height > 15 then say "Too big!" 
otherwise 


/* draw rectangle >) 


do height 
say copies("*",2*height) 
end 


say "What a pretty box!" 
end 


Figure 6-9. RECTANGL.CMD 


Conditional Loops 
A conditional expression is tested to determine how many times the loop is 
processed. Conditional loops continue running as long as some condition is 
satisfied. The three main ways to do this, depending on when the test takes place 
are: 


e DO FOREVER (with LEAVE) 
e DO WHILE (a condition is true) 
¢ DO UNTIL (a condition is true). 


Note: When you are experimenting with conditional loops, you may run into a 
situation where your program does not stop. This is called an endless loop, which 
means that the condition that controls the loop is never false. If this happens, you 
can stop the program by pressing the Control (Ctrl)+Break keys. 
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DO FOREVER with the LEAVE Instruction 
The simplest way to create a conditional loop is to use the instructions DO 
FOREVER and LEAVE. The LEAVE instruction causes processing to continue 
with the instruction following the END keyword. 


DO FOREVER 


instruction3 


END 


The mini-calculator program, ADD2NUM.CMD, shown in Figure 3-1 on page 3-1, 
adds only two numbers. Figure 6-10 shows a program that continues running as 
long as you type a number. If you do not type a number, the LEAVE instruction is 
processed and processing continues with the SAY instruction after the END of the 
loop. 


This program adds up the numbers that the user is 
invited to type. When the user types something 
/* that is not a number, a message is displayed and */ 
/* the program ends. sf 
total = 0 

do forever 


say "Type a number" 

pull entry 

if \datatype(entry,n) /*if the entry is not a valid number */ 
then leave /* leave the loop */ 


total = total + entry 
say "Total = " total 
end 


say "'"entry"' is not a number. Returning to 0S/2." 


Figure 6-10. SUM.CMD 


The other two forms of DO loops, where the conditional test (the if) is built into the 
control instruction, are: 


¢ DO WHILE 
¢ DO UNTIL. 
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DO WHILE Instruction 
To create a loop that repeats the list of instructions as long as a given condition is 
true, use the DO WHILE instruction. For example: 


DO WHILE exprw 

instruction1 

- instruction2 

instruction3 
END 


where: 


exprw (expression for while) is an expression that, when evaluated, must give a 
result of 0 or 1. 


The following is a flowchart of a DO WHILE loop. The condition is tested at the 
top of the loop, before the instruction list is processed. This means that if the given 
condition is false at the start, the list of instructions are not be processed at all. 
Compare this instruction with the flowchart showing the DO UNTIL instruction on 
page 6-15. 


DO WHILE 


instruction 
instruction2 
instruction3 


expression 


END 


Two fragments that produce the same results are: 


DO WHILE \ finished 
instructionl 
instruction2 
instruction3 

END 


or 


DO FOREVER 
if finished then LEAVE 
instructionl 
instruction2 
instruction3 

END 
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You could use DO WHILE to prompt users for data only if they forget to type an 
argument at the command prompt. For example: 


/* get the argument */ 


arg filename 
do while filename = "" /* if no argument given, then do... */ 


say "Type a file name (or a * to quit):" 
pull filename 
if filename = "*" then exit 


end 


In the previous example, if the user types a file name as a command argument, then 
the instructions within the DO WHILE loop are ignored. If no argument has been 
given, the loop is processed as long as the variable filename holds an empty string. 


DO UNTIL Instruction 


To repeat one or more instructions until a given condition is true, you can create a 
loop with the test at the bottom. For example: 
DO UNTIL expru 

instructionl 


instruction2 
instruction3 


END 
where: 


expru (expression for until) is an expression that, when evaluated, must give a 
result of 0 or 1. 


Putting the test at the bottom of the loop means that the enclosed instruction list is 
always processed at least once, even if the given condition is false at the start. 
Compare the following flowchart with the previous one for the DO WHILE 


instruction on page 6-14. 


DO UNTIL 


instruction1 
instruction2 
instruction3 


expression 


END 
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Two fragments that produce the same results are: 


DO UNTIL finished 
instructionl 
instruction2 
instruction3 

END 


or 


DO FOREVER 
instructionl 
instruction2 
instruction3 
if finished then LEAVE 
END 


The DO UNTIL instruction also provides a convenient way to check input. This 
loop uses the DATATYPE( function to ensure that the user types only a number: 


/* numbers only */ 
do until datatype(entry,num) 
say "type a number" 
say “(or press the Enter key alone to quit):" 
pull entry 
if entry = "" then exit 
end 


This loop is always processed at least once, even if the variable entry is already a 
number. It continues until the user either types a number or enters an empty string 
by pressing the Enter key. 


By typing an asterisk in the first example or a null string in the second, the user has 
a way out of the loop. It is important to include these escape clauses. Endless loops 
are frustrating to the program user. 


To Summarize 
In the three kinds of conditional loops, the decision is made: 


¢ Before processing starts. The following example of this program fills bath by 
repeatedly adding the value of bucket to it. If bath is already full (equal to or 
greater than the value of full), the body of the loop is not processed and 
nothing is added to bath. 


DO WHILE bath < full 
bath = bath + bucket 
end 


¢ After the first pass through the loop and again after every subsequent pass. An 
example is requesting valid data from a user. . 


DO UNTIL datatype(input, NUMBER) 
say "Type a number" 
pull input 

end 


6-16 REXX User’s Guide 


e During each pass. For example, the decision to leave may depend on 


information obtained during the loop. 


DO FOREVER 


say "Type an item of data. 
“no more data, type QUIT" 


pull answer 


if answer = "QUIT" then leave 
/* process the data */ 


end 


When there is", 


Be careful about the condition for repeating the loop. For DO WHILE, the 
condition must be true; for DO UNTIL, the condition must be false. 


Test Yourself 


1. What type of DO instruction would you use to code the following sequence? 


Is job done? 
instruction! 
instruction2 
instruction3 

Is job done? 
instruction! 
instruction2 
instruction3 

Is job done? 


Is job done? 


2. What type of DO instruction would you use to code the following sequence? 


instruction] 

instruction2 

instruction3 
Is job done? 

instruction1 

instruction2 

instruction3 
Is job done? 


Is job done? 


3. “Thirty days hath September, April, June, and November; all the rest have 
thirty-one, excepting February alone ...” 


Write a program that asks the user to specify the month as a number between 1 
and 12 and gives the number of days in the month in response. For month 2, 


the response can be 28 or 29. 
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Answers: 
1. DO WHILE job \= done (The first operation is to test “Is job done?”). 


2. DO UNTIL job = done (The first operation is to process the list of 
instructions.) 


3. Figure 6-11 shows a program that displays the number of days in the month. 


This program requests the user to type a whole 
number from 1 through 12 and displays the 
number of days in that month. 


until datatype (month,WHOLE) , 

& month >= 1 & month <= 12 
say “Type the month as a number from 1 through 12" 
pull month 


9 then days 

4 then days 

6 then days 

11 then days = 30 

2 then days = "28 or 29" 


when month 
when month 
when month 
when month 
when month 
otherwise 
days = 31 
end 


say "There are" days "days in Month" month 


Figure 6-11. CALENDAR.CMD 
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Using IF, SELECT, and DO 


Figure 6-12 shows a program that combines three different control instructions. It 
asks the user to provide a person’s age and sex and, in reply, it displays a person’s 
status. 


Note: 


A person under the age of 5 is a BABY. 

A person aged 5 through 12 is a BOY or a GIRL. 
A person aged 13 through 19 is a TEENAGER. 

A person over the age of 19 a MAN or a WOMAN. 


The program uses DO UNTIL to make certain that the proper input has been typed. 
It then uses SELECT to choose one of four age groups and IF, as needed, to 
determine the sex. Try the program. 


do until datatype(age,NUMBER) & age >= 0 
say "What is the person's age?" 
pull age 

end 


do until sex = "M" | sex = "F" 


say "What is the person's sex (M or F)?" 
pull sex 


COMPUTE STATUS 


Input: 
/* AGE Assumed to be 0 or a positive number. */ 
/* SEX "M" is taken to be male; =} 
anything else is taken to be female. 


Result: 
/* STATUS. Possible values: BABY, BOY, GIRL, TEENAGER *] 
MAN, WOMAN. 


when age < 5 then status = "BABY" 
when age < 13 then do 
if sex = "M" 


then status = "BOY" 

else status = "GIRL" 

end 
when age < 20 then status = "TEENAGER" 
otherwise 

if sex = "M" 

then status = "MAN" 

else status = "WOMAN" 


end 


say "This person should be counted as a" status 


Figure 6-12. CENSUS.CMD 
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Using Counters to Exit Loops 
Number each pass through the loop in such a way that you can use that number as a 
variable in your program. For example: . 


DO name = expri 
instructionl 
instruction2 
instruction3 


END 

or 

DO name = expri TO exprt 
instructionl 


instruction2 
instruction3 


END 
where: 
name is the control variable, sometimes called a counter. You can use it in 


the body of the loop. Its value is changed (in this example, increased by 
1) each time through the loop. 


expri (the expression for the initial value) is the value you want the counter 
to have the first time through the loop. 


exprt (the expression for the TO value) is the value you want the counter to 
have the last time through the loop. That is, the loop ends if the next 
time through, it puts the counter above the exprt value. 


The following flowchart shows how the counter is changed and how the decision to 
leave the loop is made. 


name = expri 


instruction1 
instruction2 
instruction3 


name > exprt 


name = name + 1 
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Bigger Steps 


Different Steps 


You can use the counter to compute something different each time through the loop. 
Figure 6-13 shows a program in which the counter is called count, and it computes 
the width of each row of asterisks. 


/* This program displays a triangle on the screen. 
/* The user is asked to specify the height of the 
/* triangle. 


say "Type the height of the triangle", 
" (a whole number between 3 and 15)." 
pull height 
select 
when \datatype(height,WHOLE) then say "Rubbish!" 
when height < 3 then say "Too small!” 
when height > 15 then say "Too big!" 
otherwise 


/* draw triangle 
do count = 1 to height 
say copies("*",2*count - 1) 
end 


say "What an ugly triangle!" 
end 


Figure 6-13. TRIANGLE.CMD 


After you have left the loop, you can still refer to the counter. It always exceeds the 
value of the TO expression (exprt). 


So far, the counter has been incremented by 1 each time through the loop. This is 
the default. To specify some other value, write: 


DO name = expri BY exprb [TO exprt] 


END 
where: 


exprb (the expression for BY) is the number that is to be added to name at the 
bottom of the loop. 


All of the expressions described for controlling loops (the TO and BY expressions 
and the counter) need not be positive whole numbers. You can use expressions that 
evaluate as decimal fractions and negative values as well. See the REXX Reference 
for examples. 
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Test Yourself 
1. Refer to the flowchart on page 6-20 and predict what the program in 
Figure 6-14 will display. 


/* Example: use of a counter */ 
do digit = 1 to 3 


say digit 
end 
say "Now you have reached" digit 


Figure 6-14. MORE.CMD 


2. What will the program in Figure 6-15 display? 


/* Example: use of a counter */ 
do count = 10 by -2 to 6 
say count 
end 
say "Now you have reached" count 


Figure 6-15. 2LESS.CMD 


3. How many lines will the program in Figure 6-16 display? 


/* Example: use of a counter */ 
do j = 10 to 8 

say "Hup! Hup! Hup!" 
end 


Figure 6-16. 3HUP.CMD 
4. How many lines will the program in Figure 6-17 display? 
/* Example: use of a counter */ 


do NOW = 1 
if NOW = 9 then exit 


say NOW 
end 


Figure 6-17. 4NOW.CMD 
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Answers: 


1. The counter is updated at the bottom of the loop. The test for leaving is made 
after this. So the counter is beyond the limit value. 


1 
2 
3 
Now you have reached 4 


2. If exprb is negative, count down: 


10 

8 

6 

Now you have reached 4 


3. None (10 already exceeds 8). 


4. Eight, (on the ninth pass, the EXIT instruction ends the program before the 
SAY instruction is reached). 


Exiting a Program 
Use EXIT [expression], to tell REXX to leave your program. If you started the 
program by typing its name at the OS/2 command prompt: 


e EXIT takes you back to the OS/2 program. 


e The result of expression must be a whole number, which is returned to (but not 
displayed by) the OS/2 program. 


Figure 6-18 shows an example using EXIT. 


/* Example: using EXIT with a return code */ 


say "Returning to the 0S/2 program" 
exit 22 


Figure 6-18. FADE.CMD 


The following is displayed on the screen, when you run this program. 


[C:\]fade 


Returning to 0S/2 
[c:\] 
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Summary 
This completes “Basics” in this chapter. You have learned how to: 


¢ Create branches in a program with IF and SELECT 
e Group instructions with DO 
e Create loops with DO FOREVER, DO UNTIL, and DO WHILE. 


“Advanced Topics” in this chapter discusses complex controls, including: 


e Nesting IF instructions 

¢ Using the NOP instruction 

e¢ Using DO with LEAVE and ITERATE 
¢ Nesting DO instructions. 


To continue with “Basics,” go to page 7-1. 
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Advanced Topics 
In this chapter: 
Advanced Topics 


Nesting IF instructions 


The ITERATE instruction 
Compound DO instructions 
Nested loops. 


Nesting IF Instructions 
You can manage more complicated situations by using IF instructions in the lists 
controlled by other IFs. This flowchart shows two successive decisions that lead to 
one of four possible outcomes. 


weather False 
IF 
True False True False 
THEN else THEN else 


say 
“shall we 
play poker?” 


say 
“shall we 
play chess?” 


say say 
“shall we "shall we take 


play tennis?” a stroll?” 


The best way to write this as a program is: 


if weather = "fine" 
then do 
if tenniscourt = "free" 
then say “Shall we play tennis?" 
else say "Shall we take a stroll?" 
end 
else do 
if players = 2 
then say "Shall we play chess?" 
else say "Shall we play poker?" 
end 


Indenting the secondary decisions to the right three spaces does not change how 
REXX processes the program. It makes it easier for someone reading the program 
to see the control structure. 
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Nested IF and SELECT 
The previous example tests each condition and moves on to the next level. It does 
not consider whether the tennis court is free until it has determined that the weather 
is fine. 


Compare this nested-IF example to one using the SELECT instruction. There still 
are four possible outcomes, but this time they are tested in parallel. 


select 
when weather = "fine" & tenniscourt = "free" 
then say "Shall we play tennis?" 
when weather = "fine" & tenniscourt \= "free" 
then say “Shall we take a stroll?" 
when weather \= "fine" & players = 2 
then say "Shall we play chess?" 
otherwise say "Shall we play poker?" 
end 


The distinction to make here is not which version works better. Rather, it is which 
of the two programs is more readable to the user who corrects and improves them. 
The results of these two programs would be the same. 


For this application, the nested-IF version shows more clearly how the decision 
whether to play tennis depends on the weather. The only priority of 
decision-making available to SELECT is the order given the WHEN keywords. 
Therefore use: 


¢ SELECT when your program must make more or less parallel decisions, 
choosing one option to the exclusion of the rest. 


¢ Nested IF when your program must make a series of decisions, each decision 
dependent on the ones that precede it. 


Dangling ELSE 
DO and END help REXX keep the ELSEs tied to the right IFs. Look at the 
following example. Avoid writing code like this, because it is too error-prone. 


/* The dangling ELSE */ 
if weather = fine 
then 


if tenniscourt = free 
then say "Shall we play tennis?" 


else say "Shall we take our raincoats?" 


/* REXX will take this ELSE to belong a} 
/* to the nearest preceding IF, but a person of 
/* reading the program might easily assume that it */ 
/* belonged to the first IF. */ 
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Test Yourself 


Programs that have IFs within IFs should use DO ... END. The following example 
pairs THEN DO with END and THEN with ELSE. 


Tt wae 
then do 
WT ees 
then do 
end 
else do 
end 
end 
else ... 


Remember, using indentation does not affect how the program is interpreted. It is 
simply a convention to make the program more readable. Readability is discussed in 
“Making Programs Easy to Read” on page 11-11. 


What will the program in Figure 6-19 do? 


/* An example of a program that does not use "DO...END" */ 
/* input data */ 

trace r 

weather = "RAIN" 

tenniscourt = "FREE" 

players = 2 


if weather = fine 
then 

if tenniscourt = free 

then say "Shall we play tennis?" 

/* else say "Shall we take a stroll?" (DELETED) - 
else 

if players = 2 

then say "Shall we play chess?" 

else say "Shall we play poker?" 


Figure 6-19. WHATTODO.CMD 


Try it! The TRACE R (results) instruction at the beginning will help you see what is 
happening. 
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Answer: Remember the ELSE keyword is associated with the nearest preceding IF. 
The following flowchart shows what happens when these values are given for 
weather, tenniscourt, and players. 


say 
“shall we 
play tennis?" 


say 
“shall we 
play chess?" 


say 
"shall we 
If the weather is anything but fine, the program displays nothing. It never considers 


how many players are available. The trace ofp WHATTODO.CMD program 
displays: 


[C:\]whattodo 
3 K* 


weather = 'RAIN's 

>>> u RAI N LU 

tenniscourt = 'FREE'; 
"FREE' 

players = 2; 
a 2 iu 

If weather = 'FINE'S 
u 0 ul 
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NOP Instruction 


A THEN or ELSE keyword must be followed by an instruction. A semicolon is not 
sufficient. In cases where you intend that nothing should be done, use a NOP (no 
operation) instruction. You could use the NOP instruction to add an ELSE 
keyword in WHATTODO.CMD in Figure 6-19 on page 6-27. For example: 


if weather = fine 
then 
if tenniscourt = free 
then say "Shall we play tennis?" 
/* else say "Shall we take a strol1?" (DELETED) 5 
else NOP 
else 
if players = 2 
then say "Shall we play chess?" 
else say "Shall we play poker?" 


The following flowchart shows how the program flow is changed to. 


THEN 


say 
"shall we 
play tennis?” 


play poker?” 


play chess?” 


Figure 6-20 and Figure 6-21 on page 6-30 show examples using the NOP 
instruction. 


/* Example: steering a course 


Say "Where is the harbor?" 
pull where 
select 
when where = "AHEAD" then nop 
when where = “PORT BOW" then say "Turn left" 
when where = "STARBOARD BOW" then say "Turn right" 
otherwise say "Not understood" 
end 


Figure 6-20. PILOT.CMD 
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/* Example: using NOP to simplify the presentation of 
/* a set of conditions. 


If gas = "FULL" & oi] = "SAFE" & window = "CLEAN" 
then nop 
else say "Find a gas station!" 


Figure 6-21. TRUCKER.CMD 


ITERATE Instruction 
To bypass all remaining instructions in the loop and test the ending conditions, use 
the ITERATE instruction. Similar to LEAVE, ITERATE can be introduced by a 
THEN or ELSE keyword. Instead of leaving the loop altogether, REXX proceeds 
with the operations usually done at the bottom of the loop. If an UNTIL condition 
is specified, it is tested; if a counter is specified, it is incremented and tested; and if a 
WHILE condition is specified, it is tested. 


If tests indicate that the loop is still active, then normal processing continues from 
the top of the loop. For example: 


DO j = 1 to limit by delta 
instructionl 
instruction2 
if condition 
then do 

instruction3 

instruction4 

ITERATE j 
end 
instruction5 
instruction6 

END 
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“Nee 


The following flowchart shows the program flow. 


instruction1 
instruction2 


instruction3 
instruction4 
ITERATE j 


instruction5 
instruction6 


j = j + delta 
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Compound DO Instructions | 
You can combine one repetitive phrase and one conditional phrase in a single DO 
instruction. You should know where in the loop the counters are updated and where 
the tests for leaving the loop are made (see “Conditional Loops” on page 6-12). 


Compound DO instructions can do a lot of useful work. Figure 6-22 shows an 
example of how a simplified version of the POSQ function may be implemented as a 
REXX function. 


/* Example: the POSN() function is similar to the 
/* POS(), except that the third argument ("start") 
/* is not allowed 


if arg() \= 2 
then return /* wrong number of arguments 


if arg(1,omitted) 
then return /* argument was omitted 


parse arg needle, haystack 
last = length(haystack), /* compute the rightmost 


-length(needie)+1 /* position that needle could 
/* be found in 


do result = 1 to last, /* Search for needle 
until substr(haystack,result, length(needle)) = needle 
end 
if result > last then result = 0 
return result 


Figure 6-22. POSN.CMD 
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Nested Loops 
Sometimes a program is constructed of loops within loops. When you leave a loop, 
you may need to specify which loop you want to leave. To do this, give a DO loop 
a name (specify a counter in the DO instruction). If the loop does not contain a 
counter already, create one. For example: 


DO outer = 1 


END 


This is the same, for all practical purposes, as DO FOREVER. In the previous 
example, outer is the counter for the loop. To leave a specific loop, put the name of 
its counter after the keyword LEAVE. For example: 


DO outer = 1 


do until datatype(answer,WHOLE) 
say "Type a number. ", 
"When you have no more data, enter a blank line" 
pull answer 
if answer = "" then leave outer 
end 


/* process answer */ 
end 
/* come here when there is no more data */ 
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Chapter 7. Program Structure 


This chapter discusses a different type of program-control—using instructions that 
run one program from within another. Using these subsidiary programs or 
subroutines can actually make programming easier. 


a 


Basics 


In this chapter: 


Basics 


Subroutines 

External subroutines 
Using arguments 
Subroutines and data. 


Subroutines 
A subroutine is a segment of program code that can be called from more than one 
place in your main program. Subroutines can reside in the same file as the main 
program or they can reside in a separate REXX program file. The following 
diagram shows a subroutine that is in the same file as the main program. 


CALL mysub 


Main program 


EXIT 


MYSUB: 


Subroutine 


RETURN 


~ A CALL instruction tells REXX to look through the program until it finds a 
corresponding /abel, a clause that marks the start of the subroutine. 
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REXX processes the instructions following the label until it encounters a RETURN 
instruction. RETURN tells REXX to resume processing in the main program, 
beginning with the instruction immediately after the CALL. 


A subroutine can be called from more than one place in a program. That is, several 
CALL instructions can use the same subroutine. The subroutine always returns 
processing to the clause following the last CALL instruction. 


Each CALL instruction can supply data, called arguments, which the subroutine can 
use when called. In the subroutine, you can determine the data supplied by using 
the ARGO function or the ARG instruction. 


CALL Instruction 
Figure 7-1 shows an example of how to have REXX run a subroutine at a particular 
point in a program: 


CALL subname [argument1, argument2 ...] 
where: 


subname is the name of the subroutine. REXX searches first for the 
corresponding label in your program. A label consists of a 
symbol followed by a colon (:). For example: 


subname: 


If no such label is found, REXX looks for a built-in function 
or program file named subname. (See the search order in 
“Comparing Subroutines and Functions” on page 7-13.) 


argument is any data that you want passed to the subroutine. The 
subroutine can collect the arguments with the ARG instruction 
or the ARGO function. 


Figure 7-1 shows a program that displays the squares of numbers from 1 to 5. The 
calculation is performed in a subroutine. 


/* Simple example of using CALL instruction */ 

trace r /* we turn on tracing 
/* so you can see the 
/* subroutine in action 


say "This is the main program" /* remark 1 
do num = 1 to 5 
call square /* calls subroutine 
say "Back in the main program." /* remark 3 
say num “squared is" num2 /* display result 
end 
exit /* end the program 


square: /* subroutine begins */ 

say "This is the subroutine." /* remark 2 

num2 = num * num /* calculate square */ 
return /* resume main program */ 


Figure 7-1. SQUARIT.CMD 


Try this program without the TRACE instruction and extra remarks. 
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RETURN Instruction 


Test Yourself 


The RETURN instruction takes processing back to the main routine. Processing 
continues with the instruction following the last CALL. The full form of the 
instruction is: 


RETURN [expression] 


where, if expression is specified, it is assigned to the REXX special variable, 
RESULT, which can then be used by the main program. But, if expression is 
omitted, RESULT is dropped and not assigned a value. Its value is its own 
name—RESULT. 


Figure 7-2 shows a program that simulates a children’s race game that used to be 
played with dice. Write the subroutine TELL to tell who is winning. 


/* Example of a subroutine: a child's race game 

a /* Arthur starts from zero 
b /* Barry gets a headstart of 3 
d 


ol 
a= a+ random(1,6) /* Arthur gets first turn 


call tell /* Who's ahead now 
b = b + random(1,6) /* Now it is Barry's turn 
call tell /* Who's ahead now 

end 

exit /* End of main program 


Figure 7-2. RACEGAME.CMD 


Copy the main program and your subroutine into another file and test your 
program. 


Answer: Figure 7-3 is an example of a possible solution. 


INPUT: a (Arthur's score) 
b (Barry's score) 
RESULT: displayed on user's screen 


values = “Arthur =" a "3; Barry ="b "; " 

select 
when a > b then say values "Arthur is ahead" 
when b > a then say values "Barry is ahead” 
otherwise say values "Neck and neck!" 

end 

return 


Figure 7-3. RACEGAME.CMD Subroutine 
In this sample solution, there are no arguments on the CALL instruction. 


Nevertheless, a person reading the program needs to know what data the subroutine 
is using. 
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A well-designed subroutine operates on a clearly defined set of data. To make your 
program more readable, you should define this data in comments at the beginning of 


the subroutine. 


External Subroutines 
The subroutines that have been discussed are internal routines. Subroutines can also 


exist as a separate REXX program file. The following diagram shows a subroutine 
that is a separate REXX program file. 


CALL mysub 


MYSUB EXEC 


RETURN 


In an external routine, the variables belonging to the calling routine are not available 
to the subroutine. Therefore, data: 
¢ Must be formally passed to the subroutine as arguments to the CALL 
instruction. 


¢ Can only be returned to the caller by assigning a value to the variable RESULT, 
using the RETURN instruction. If necessary, the calling routine can then parse 
the RESULT value into a number of variables. 


Note: The variables of the CALL are available to an internal subroutine unless you 
use the PROCEDURE instruction (see “PROCEDURE Instruction” on page 3-16). 
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Using Arguments 


In the example shown in Figure 7-4, type the program name, add, followed by the 
two numbers to be added. The numbers are assigned to variables first and second 
by the ARG instruction. Information given to a program in this manner is called an 
argument. That is, the numbers given ADD.CMD to add together are arguments to 
the startup command, ADD. 


/* the sum of two numbers, this time */ 
/* typed at the command prompt */ 


arg first second /*collects entries */ 
say "The sum is" first + second 


Figure 7-4. ADD.CMD 


In much the same way, you can provide a subroutine with the needed information 
by arguments passed by the CALL instruction that starts the subroutine. To assign 
the arguments to variables, you can use the ARG instruction or the PARSE ARG 
instruction. 


The difference is: 


ARG assigns argument data to variables, translating lowercase letters 
into uppercase. In this way, ARG is similar to PULL. ARG is the 
short form of the instruction PARSE UPPER ARG. 


PARSE ARG assigns the information to variables exactly as it is entered, with no 
translation to uppercase. 


For example, here is a CALL instruction: 
CALL BAKE "white", "fresh", "sweet", "dessert" 


If you want the results of these four expressions assigned to flour, butter, sugar, 
and cookies, you would write: 


PARSE ARG flour, butter, sugar, cookies 


But, if you wanted the four arguments to be translated to uppercase, you would 
write: 


ARG flour, butter, sugar, cookies 


As there are commas between the expressions in the CALL instruction, there are 
likewise commas between the symbols in the PARSE ARG or ARG instruction 
when it is used in this way. For example, the instruction: 


CALL words “a string of words",5 
might be parsed using: 


WORDS: 
PARSE ARG first second third fourth rest, number 
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The result would be that: 


first gets a 
second gets string 
third gets of 
fourth gets words 
rest gets (blank) 
number gets 5 


Figure 7-5 is an example of the main program, that shows how: 


¢ CALL passes arguments to a subroutine. 

e ARG assigns the argument values to variables. 

¢ RETURN assigns a value to the RESULT variable. 
¢ RESULT is used by the main program. 


/* Main program to gather input and display result #/ 
Say "To calculate the material you need to make a box," 


/* Input the dimensions of the desired box (meters) * 


say "type the desired length of the box:" 
pull length 


say “type the desired width:" 
pull width 


say "type the height:" 
pull height 


/* call the subroutine program BOX.CMD with arguments */ 
CALL box length, width, height 
/* report the returned value from the RESULT variable */ 


SAY "Material required =' RESULT 'square meters' 
exit 


Figure 7-5. MAKEBOX.CMD 


Figure 7-6 is the subroutine program called by MAKEBOX.CMD. 


/* computes area of a box */ 
/* including a lid *] 


ARG long, wide, high 


/* total area is base and top plus */ 
/* short sides plus long sides */ 


area = 2*(long*wide) + 2*(wide*high) + 2*(long*high) 


RETURN area 


Figure 7-6. BOX.CMD 


7-6 REXX User's Guide 


When you run MAKEBOX, the data you enter is gathered by the PULL instructions 
and then passed, as arguments of CALL, to BOX.CMD. The calculation of the area 
of the box is then passed back to MAKEBOX.CMD by the RETURN instruction to 
the variable RESULT. Processing of MAKEBOX then resumes with the next clause 
following the CALL. 


The following diagram shows the flow of data between the two programs. 


MAKEBOX. CMD 


/* Main program to gather input and display result */ 
say "To calculate the material you need to make a box," 


say "type the desired length of the box:" 
pull length 


CALL box length, width, hei 


SAY 'Material required =' RESULT ‘square meters' 


exit 


/* Computes area of a box, including a lid */ 


ARG long, wide, high 
area = 2*(long*wide) + 2*(wide*high) + 2*(long*high) 


RETURN area 


BOX. CMD 


If program variables are referred to by the same names both outside and inside an 
internal routine (a routine that exists in the same file as the CALL instruction), then 
it is not necessary to include them as arguments on the CALL or ARG instructions. 
However, not including them could make it more difficult for a user reading your 
program to understand what your subroutine does. So it is a good idea to give a list 
of the arguments in the comments that introduce the subroutine. 
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ARG() Function 
Another way to pass arguments to a subroutine is to use the ARG function. For 
example: 


CALL subname [argument1, argument2 ...] 


where: 

subname is the name of the subroutine. 

argument1, argument2,... are expressions. The value of each is computed and can 
be obtained in the subroutine by using the ARGQ 
function. 


ARG(1) returns the first argument 
ARG(2) returns the second argument 
and so on... 


You can have up to 20 arguments on a CALL 
instruction. 


Figure 7-7 shows an example that calls a subroutine using arguments. 


/* Example: calling a subroutine with arguments */ 

do 3 
call triple "R" 
call triple "E" 
call triple "X* 
call triple "X" 
say 

end 

say 

say 

say 


/* end of main program */ 


/* Subroutine to repeat a shout three times 
* 


/* The first argument is displayed on the screen, three */ 


say arg(1)", “arg(1)", “arg(1)"!" 
return 


Figure 7-7. CHEER.CMD 


7-8 REXX User’s Guide 


The following is displayed on the screen when you run the program. 


The EXIT instruction in Figure 7-7 on page 7-8 stops the main program from 
running on into the subroutine. 


Subroutines and Data 


Summary 


Passing arguments to a subroutine is one form of parsing input information. This is 
a particularly important concept in REXX. 


The best starting point for a large program is to study the information that you want 
REXX to work with. The next few chapters concentrate on how to analyze and 
calculate data and how REXX shares information with other programs and devices. 


This completes “Basics” in this chapter. You have learned how to: 


¢ Use subroutines with the CALL and RETURN instructions 

¢ Use subroutines in the same program file as the main program or in a separate 
file 

e Pass data to a subroutine, using the ARG instruction and the ARG function. 


“Advanced Topics” in this chapter discusses advanced elements of program 
structure, including: 


¢ Modular programming 
e Creating your own functions 
e¢ Jumps and condition traps. 


To continue with “Basics,” go to page 8-1. 
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Advanced Topics 
In this chapter: 


Advanced Topics 


Structured programming 
Function calls 


Comparing subroutines and functions 
Jumps 
Condition traps. 


Structured Programming 


Using the CALL instruction to call a subroutine is part of an approach to 
programming called structured programming. 


Experienced programmers rarely write complex programs as a single list of 
instructions. Rather, they separate a large job into smaller units called modules. 
Then, they create a single main module that calls all the others, either in a specific 
listed order or by means of control instructions such as IF, SELECT, and DO. For 
example: 


Main program module Subroutine modules 


oe Ce 
SELECT 
WHEN...THEN CALL c 


WHEN... THEN CALL d ———~ d [| 
WHEN... THEN CALL e 
OTHERWISE SIGNAL q 

: Le 


DO UNTIL done 
END 


q: 
EXIT 


Structured programming helps programmers in the following ways: 


e It makes planning a program easier because large projects can be separated into 
smaller tasks that are easier to understand. 
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Function Calls 


Creating a Function 


e It makes the finished program more readable by users. This is a definite help 
when correcting and improving the program. You can fix and enhance one 
module at a time. Errors are easier to trace, and the overall structure is clearer. 


e As you become more fluent in the REXX language, you become more adept at 
defining the work a program can do. You can define clearly what a module 
should do before you write a line of program code. For example, the program 
code you write will have applications beyond the task it was written for. A 
clever routine for sorting a directory might prove useful in another 
fileemanagement program. 


For more information about structured programming, refer to Chapter 11, 
“Program Style.” 


A subroutine can produce a computed result, or return value, that the calling 
procedure can use. The RETURN instruction does this (see “RETURN 
Instruction” on page 7-3). You have the following options: 


e Use CALL to call the subroutine and then get the return value from the built-in 
variable RESULT. 


¢ Call the subroutine as a function call, the same way that you call the REXX 
built-in functions. 


A subroutine called by a function call is essentially no different than any other 
subroutine that returns a value. That is an important distinction, because the very 
definition of a function is that it always returns a value, even if that value is a null 
string. 


Arguments of the function (the input that goes between the parentheses in the 
function call), can be read with the ARG instruction or with the ARG function. 


Since functions always return a value, they are normally used in expressions, such as 
in a SAY instruction. If you write a function call on a line by itself, the value 
returned by the function is passed to the system as a command. For example, if you 
write Word('Now is the time',3), REXX passes 'the' to the system as a command. 
If you are calling a function but do not need the value returned, call the function as 
a subroutine. 


Figure 7-8 on page 7-12 shows a subroutine that calculates and returns the average 
number of letters per word. 
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/* Returns the average letters per word in an input line */ 
* get the line; set TOTAL to 0 */ 


arg line 
total = 0 


do num = 1 until line = "" /* repeat until LINE is empty, 
adding 1 to NUM with each 
iteration 


parse var line word line take out just the first word 
remaining in LINE 


total = total + length(word) /* add its length to TOTAL 


end /* see if LINE is empty yet... 
/* if so, the loop ends. 


avg = format(total /num, ,0) now, divide TOTAL (letters) 
by NUM(ber of words) to get 
the average per word 


return avg return the number AVG 


Figure 7-8. WORDAVG.CMD 


You can also create functions that return non-numeric values, as shown in 
Figure 7-9. 


/* Returns today's date in ‘natural language’ format */ 


/* First, use DATE() function and its options to... 

month = date(m) /* ...get the month 
day = date(w) /* ...get the weekday 
parse value date() with cdate. . /* ...get the date 


/* The RIGHT() function returns the last digit of the date 
/* so we can add on the proper suffix (similar to the way 
/* we used for Figure 3-9 on page 3-11.*/ 
select 
when right (cdate,1) 
when right (cdate, 1) 
when right (cdate,1) 
otherwise th = "th" 
end 


a "ot" 
= "nd" 
= 3 then th = "rd" 


return day"," month cdate}!th /* return the date 


Figure 7-9. DATESTMP.CMD 
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Comparing Subroutines and Functions 
There are differences and similarities between subroutines and functions. 


The differences are: 

¢ To call a subroutine, you use a CALL instruction: 
CALL routine [argumentl, ... ] 
To call a function, you use a function call: 
routine([argumentl, ... ]) 

e A subroutine need not return a result, but a function must return a result. 
In a subroutine, you can write: 
RETURN 
In a function you must at least write: 
RETURN "" /* This returns a null string */ 


e A subroutine sets the value of the special variable RESULT. The result returned 
by a function is used in the expression where the function call appeared. 


The similarities are that both: 


e Use the ARG and PARSE ARG instructions and the ARG(Q function for 
obtaining the values of their arguments. 


¢ Can be internal (starting with a label in the same file as the CALL instruction or 
the function call) or external (located in a different file). 


¢ Have the same search order. When a call to routine is recognized: 


1. REXX first looks for the label routine: in the same file. 

2. If no label by that name is found, REXX looks for a built-in function called 
routine(). 

3. If none of its own functions have that name, REXX looks for an external 
routine; that is, a program in a file named routine. 


There are many kinds of external routines that REXX can use, including those 
written in other languages. These are made available to REXX through function 
packages, which are described in the REXX Reference. 


Using a Call of the Other Kind 
There is another similarity between functions and subroutines. Where convenient, 
programs designed as functions can be called as subroutines. If they always return a 
result, programs designed as subroutines can be called as functions. Both, when they 
are internal, can use the PROCEDURE instruction. 


You could eliminate the CALL instruction in MAKEBOX.CMD (see Figure 7-5 on 
page 7-6) and simply call the subroutine BOX.CMD (see Figure 7-6 on page 7-6) as 
a function in the final SAY instruction. For example: 


say "Material required =" box(length,width,height) "sq. meters" 


In the following example, the POSQ function returns the character position of a 
substring (needle) within a larger string (haystack). 


POS (needle, haystack) 
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Jumps 


SIGNAL Instruction 


Figure 7-10 shows an example that is called as a subroutine. 


/* to remove NEEDLEs from haystack */ 
do forever 
call pos needle,haystack 


if result = 0 
then leave 
else haystack = delstr(haystack, result, length(needle) ) 


Figure 7-10. NEEDLE.CMD 


This routine removes every instance of one string within another. It uses the 
DELSTRO and LENGTHO functions, which are also built into REXX, and are 
called here as functions. In this example: 


1. POSO, called as a subroutine, searches in the string stored in haystack for the 
first occurrence of the string in needle. 


2. That character position (a number) is then assigned to the RESULT variable. If 
no occurrence if found, the loop ends. 


3. DELSTRO then removes the needle substring from haystack, deleting from the 
RESULT starting position, for the length of needle (determined by the 
LENGTHO function). 


A jump shifts REXX processing to a different point in the program. After the jump, 
the program does not automatically return to the calling instruction. 


The SIGNAL instruction can jump (transfer control) to another part of your 
program. SIGNAL is a one-way path. When REXX encounters a SIGNAL 
instruction in the middle of a program, any SELECT constructs or DO loops it has 
been processing are abandoned. SIGNAL cannot be used to jump back into or 
jump around within a DO loop. This means that you should use SIGNAL only to 
bring your program to an exit. For other purposes, it is better to manipulate 
program control using IF, SELECT, or DO. 


To tell REXX to go to another part of the same file, use the instruction: 
SIGNAL symbol] 
This causes a jump to the specified label, the symbol followed by a colon (:). REXX 


searches from the top of the file for the clause symbol: and processing continues 
from there. 


The SIGNAL instruction always stores its line number in the REXX special variable 
SIGL. 
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Condition Traps 


This is an example of an abnormal end to a program using SIGNAL. 
SIGNAL abend 


EXIT /* end of ordinary code */ 
a ke a a hn eee ee * 
/* This code handles abnormal ends *] 
IO a oe Ce eww occ cee we eeu en wedkeecoeece coos */ 

ABEND: 


say "Abnormal end signalled at line" sigl, 
\!". Cannot continue." 


exit 


The first EXIT instruction is there to stop the normal program from running on into 
the abend: (abnormal end) routine. 


SIGNAL is not a go to statement similar to the BASIC instruction GOTO, because 
SIGNAL causes the logic of other control structures to be abandoned. The concept 
of go to does not really apply to a structured language such as REXX. Most tasks 
or routines that are to be performed according to some condition are better handled 
as subroutines. They are easier to read that way, and they are easier to correct. 


The exception is when you use SIGNAL to call an exit routine. This is a specific 
application of SIGNAL, to act as a detector to bring a program to an end whenever 
a specific condition occurs. In other words, you can set a trap. 


The SIGNAL instruction by itself initiates a jump from one particular point in a 
program (the SIGNAL clause) to another, indicated by a label. 


Another way to use SIGNAL is with the keyword ON and the name of a specific 
condition that you want REXX to test for. Whenever the specified condition is 
detected, processing immediately jumps to the corresponding label. For example: 


SIGNAL ON condition [NAME trapname] 
When a SIGNAL ON instruction is in effect (enabled) and the given condition 
occurs, REXX jumps to a label that can be either: 

e The name of the condition itself (the default) 

e¢ An optional trapname, specified by the NAME keyword. 


This trap remains enabled for the rest of the program or until issued the instruction: 
SIGNAL OFF condition 


These are the conditions that can be trapped by SIGNAL ON instruction: 


ERROR Sets a trap to a subroutine with the label ERROR:. An ERROR 
condition occurs whenever a REXX program issues a 
command (a string expression passed to the environment) that 
results in an error in the default environment. This includes 
commands that produce nonzero return codes and commands 
that are unknown to the system. (This includes failures only 
when a FAILURE condition trap is not set.) 
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FAILURE 


NOTREADY 


NOVALUE 


SYNTAX 


Sets a trap to a subroutine with the label FAILURE:. A 
FAILURE condition occurs whenever a REXX program issues 
a command to the default environment and the system 
encounters a severe error preventing it from processing the 
command. 


Refer to “Trapping Command Errors” on page 5-14 for more 
information. 


Sets a trap to a subroutine with the label NOTREADY:. A 
NOTREADY condition occurs whenever an error occurs 
during an input or output operation. (Refer to Chapter 10, 
“Input and Output,” for more information.) 


Sets a trap to a subroutine with the label NOVALUE:. A 
NOVALUE condition occurs whenever a symbol that could be 
the name of a variable is encountered and the variable does 
not exist. This can be especially useful for finding misspelled 
variable names. 


Sets a trap to a subroutine with the label SYNTAX:. A 
SYNTAX condition occurs whenever a REXX syntax error is 
detected. This is especially useful for debugging programs in 
which syntax errors occur, but the user is unable to provide an 
accurate description of the problem. 


If the trap you have set with SIGNAL ON detects one of the previous conditions: 


1. REXX stops whatever instruction it is processing. 


2. The line number of that instruction is assigned to the special variable SIGL. 
3. The condition is disabled; it is set to SIGNAL OFF. 
4 


. Processing then jumps (as in a normal SIGNAL) to the appropriate label (to 
trapname:, if given; otherwise, to condition:). 


Using CALL ON 


In certain instances, it is possible to resume program processing after a condition is 
trapped. In such an instance, use the instruction: 


CALL ON condition [NAME trapname] 


See “Trapping Command Errors” on page 5-14 for an example comparing the 
CALL ON and SIGNAL ON instructions. 


Useful Functions 


The following two functions you may find useful: 


CONDITIONQ Returns the keyword (CALL or SIGNAL) used to trap the 


VALUEQ 


condition. Used with its options, CONDITIONO(O can also supply 
the name of the trapped condition (for example, ERROR), its 
status (ON, OFF, or DELAY), or an associated description. 


Returns or sets the value of a variable whose name may be a string 
expression. VALUE() does not trigger a NOVALUE condition. 


For more information about these instructions and functions, refer to “Conditions 
and Condition Traps” in the REXX Reference. 
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Chapter 8. Parsing 


Parsing is a way of analyzing information for your program to use. It is one of the 
most powerful and practical features of the REXX language. You may have noticed 
that it has already been used in many examples. This chapter discusses these ideas 
and examines the parsing options one by one. 


Parsing is separating input data and assigning it to one or more variables. Some 
examples of sources of the input data are: 


¢ The keyboard—more specifically, any data a user types in while a program is 
running 


e An input parameter—an option typed after the command that starts a program 


e An external data source—such as a queue or a disk file. 


I 


Basics 
In this chapter: 
Basics 
> Conversations 
> Parsing variables and expressions 
> Specialties. 
Conversations 


The most common source of input data is the person using the program. The 
following is a review of the instructions you use to converse with the user of your 
program—that is, to allow that person to direct the program’s processing. 


Prompting the User for Input 
To display information on the screen, use SAY expression. The expression is 
evaluated and the result is displayed as a new line on the screen. For example, say 
3 * 4 "= twelve" causes the following to be displayed on the screen. 
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If you want to display a clause that occupies more than one line in your program, 
use a comma at the end of a line to indicate that the expression continues on the 
next line. For example, the instruction: 


say "What can not be done today, will have to be put off", 
"until tomorrow." 


causes the following to be displayed on the screen: 


| What can not be done today, will have to be put off until tomorrow. 


The continuation comma is replaced by a blank when the expression is displayed. 
Remember that the continuation comma cannot be enclosed in quotes or REXX will 
consider it part of the string. 


Having asked the user a question using SAY, you can collect the answer using 
PULL. When pull symbol is processed, the program pauses for the user to type 
data on the command line and press the Enter key. Whatever the user types is 
translated to uppercase and then assigned to the variable symbol. 


The PULL instruction is a short version of the instruction PARSE UPPER PULL, 
which converts lowercase letters in the user input to uppercase. The program 
recognizes a user’s response whether it is in uppercase, lowercase, or mixed case. To 
get the data as it is, without this conversion, use the form: 


PARSE PULL symbol 


Figure 8-lshows an example that uses both PULL and PARSE PULL. 


/* Another conversation */ 
say "Hello! What is your name?" 
parse pull name 


say "Say," name", are you going to the party?" 
pull answer 

if answer = "YES" 

then say "Good. See you there!" 


Figure 8-1. CHITCHAT.CMD 
The user’s name is displayed exactly as it was typed, but answer is translated to 


uppercase. This simplifies the program by ensuring that the same action is taken 
regardless of the way the user types the word yes. 
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Test Yourself 
1. Figure 8-2 shows a program that asks a question. 


/* Simple question (?) */ 
say "Mary, Mary, quite contrary" 
say "How many letters in that?" 


pull ans 

if ans = length(that) 
then say "Quite right!" 
else say "Oh!" 


Figure 8-2. RIDDLE.CMD 


What is displayed on the screen, if the user responds: 


e 21 
e 4 
e Four. 


2. What is displayed on the screen when you run the program shown in 
Figure 8-3? 


/* Example: expressions that continue for more 
/* than one line. 
x = 3 
say Ny =" x 
say 
say "Ham,", 
"Shem", 
“and Japheth" 
say "Silly" 
"Billy" 


Figure 8-3. NOAH.CMD 


3. Create a file called PULLIN.CMD, type the program shown in Figure 8-4, and 
try to run the program. 


/* Example: appending input, using PULL, 
/* to a REXX variable 
text = Wu 
do until input = "QUIT" 
say "Text so far is:" 
say text 


say "Would you like to add to that?", 
" If so, type your message.", 
" If not, type QUIT." 
pull input 
text = text||input 
end 


Figure 8-4. PULLIN.CMD 
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Did the program run correctly? If not, study the error messages and make sure 
you copied everything correctly. Notice that: 


¢ When you run the program, everything you type is changed to uppercase 
letters. 


¢ There are not any blanks between the old text and the new input. 


4. Change pull input to parse pull input. Change the concatenate operator 
“|[” to a single blank, then try the program again. On the OS/2 operating 
system, | can also be used as the concatenation operator. See “Basic Operators” 
on page 4-2 for additional information. 


Notice that: 
¢ Your input does not get changed to uppercase. 
¢ There is always one blank between the o/d text and the new input. 
¢ You cannot exit the program by typing quit, but you can exit by typing 
QUIT. 
Answers: 
1. This is displayed on the screen: 


e Oh! 
¢ Quite right! 
¢ Oh! 


2. This is displayed on the screen: 
[C:\]noah 
x = 3 


Ham, Shem and Japheth 
Silly 


(C:\]BILLY 
SYS1041: The name specified is not recognized as an 
internal or external command, operable program or batch file. 


[c:\] 


Because there is no comma after Silly, Billy is treated as a command. If no 
such command exists, then the OS/2 program issues an error message. 


Getting Data When the Program Starts 
When you want to run your program, type its file name at the command prompt. 
This can be followed by information for the program to use in the form of 
arguments. To use these arguments in the program, use the ARG instruction. ARG 
parses command arguments in the same way that PULL parses data from the 
keyboard, except that the first word typed (the name of the program) is ignored. 
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Figure 8-5 shows an example of how a parsed argument can be used in a SELECT 
instruction. 


telephone tickler: displays the phone number */ 
of a person whose NAME is given as the */ 
argument; e.g., the command "phone anne" - 

displays "ANNE'S NUMBER IS 555-3434" */ 


arg name /* get the name */ 


select 
when name 
number 
when name 
number 
when name 
number 
when name 
number 
when name 
number 


"WILLIAM" then 
"555-1212" 
"ANNE" then 
"555-3434" 
"{QUISE" then 
"555-5656" 
"STEVE" then 
"555-7878" 
"HELEN" then 
"555-9090" 


otherwise 
say "I do not have that number." 
exit 
end 


say name}!"'S NUMBER IS" number} {"." 
exit 


Figure 8-5. PHONE.CMD 


The ARG instruction is the short form of the PARSE UPPER ARG instruction. To 
obtain arguments without the uppercase translation of letters, use the PARSE ARG 
instruction instead. 


Multiple-Variable Assignment 
PULL and ARG can also fetch each word into a different variable. In the following 
example, first, second, third, and leftover have been chosen as the names of 
variables. 


say "Please enter three or more words:" 
pull first second third leftover 


say first second third leftover 


The following is displayed on the screen. 
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Please type. three or more words 


three wise men on camels the user types 


THREE WISE MEN ON CAMELS the program displays 


second 


leftover 


The program pauses and the user can type something on the command line. When 
the user presses the Enter key, the program continues and the variable: 


first is given the value THREE. 

second is given the value WISE. 

third is given the value MEN. 

leftover is given the value ON CAMELS. 


In general, each variable gets a word (without blanks) and the last variable gets the 
rest of the input, if any (with blanks). If there are more variables than words, the 
extra variables are assigned the null value. 


The same thing can be done with ARG. Figure 8-6 shows a program that accepts 
user input and then displays it in a different order. 


/* Example: this program starts by assigning the words 
/* from the command line to REXX variables and then 
/* displays them, swapping the first and third arguments. */ 


arg first second third rest 
say third second first rest 


Figure 8-6. MIX.CMD 
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The following is displayed on the screen. 


[C:\] mix james joe jack and jeff 


JACK JOE JAMES AND JEFF 


When the ARG instruction is processed, the variable: 


first is given the value JAMES. 
second is given the value JOE. 
third is given the value JACK. 
rest is given the value AND JEFF. 


You can then use the SAY instruction to display the variables in any order you 
choose. 


Checking for Input Errors 
To ensure that the user types in the right number of words, provide one extra 
variable and test that it is empty. Also, test the variable that holds the last word 
that the user is expected to type. By testing both variables for a null value, you can 
be sure that each of your variables contains exactly one word. 


Figure 8-7 shows an example that ensures that the user has typed the correct 
number of words. 


/* Example: getting the number of words that you want */ 


good = 0 

do until good 
say "Please type exactly three words" 
pull first second third rest 


select 


when third = "" then say "Not enough words" 
when rest \= "" then say "Too many words" 
otherwise good = 1 
end 
end 


Figure 8-7. FUSSY.CMD 


Using a Placeholder 
The period symbol (.) by itself may not be used as a name, but it may be used as a 
place-holder with the PULL instruction. For example, pull . . lastname ., 
would discard the first two words, assign the third word into lastname, and discard . 
the remainder of the input. 
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Test Yourself 
1. What is displayed on the screen when you run the program shown in 
Figure 8-8? 


/* Example: the PULL instruction */ 
Say "Where did Jack and Jill go?" 
parse pull one two three four five six . 


/* User replies ‘To fetch a pail of water' */ 


say one two six 

say 

Say "Will you buy me a diamond ring?" 
pull reply . 


/* User replies 'Yes, if I can afford it' */ 


say reply 


Figure 8-8. PULLING.CMD 


2. Write a program that asks users for their name and then greets them by first 
name only. Your program should ignore any other names. 


Answers: 
1. The following is displayed on the screen. 
Where did Jack and Jill go? 
To fetch a pail of water 
To fetch water 
Will you buy me a diamond ring? 


Yes, if I can afford it 
YES, 


2. Figure 8-9 shows an example of a possible answer. 


/* Example: selecting a single word */ 
say “Howdy! Say, what is your name?" 


pull reply . /* The period causes second */ 


/* and subsequent words to */ 
/* be ignored *] 


say "Pleased to meet you," reply 


Figure 8-9. HOWDY.CMD 
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Parsing Variables and Expressions 


PULL and ARG are the short versions of options of the PARSE instruction. As 
well as parsing replies from the user and the data from the command line, you can 
also parse: 


e The values of variables by using PARSE VAR symbol vl v2 v3 ... 
e The results of expressions by using PARSE VALUE expression WITH v1 v2 v3 ... 


Figure 8-10 shows an example of parsing variables and expressions. 


/* Examples of parsing variables and expressions 
phrase = "Three blind mice " 

PARSE VAR phrase number adjective noun 

say number /* says 'Three' 

say adjective /* says ‘blind' 

say noun /* says 'mice' 

PARSE VALUE copies(phrase,2) WITH. a.b.c 

say bac /* says ‘Three blind mice' 


/* Here is a very useful trick for taking */ 

/* the first word away from a sentence if 
PARSE VAR phrase first phrase 

say first /* says 'Three' 

say phrase /* says ‘blind mice' 


Figure 8-10. PARSING.CMD 


You can use parsing to analyze data from sources other than user input, such as 
from files, queues, or hardware devices. For more information, see Chapter 10, 
“Input and Output.” 


Parsing Numeric Data 


Summary 


Only parsing text data has been discussed, but all of the parsing options that have 
been described work equally well with numeric data. 


The way REXX handles numbers is another measure of its flexibility. Most 
computer languages have many rules about the differences between text data and 
number data. In REXX, a number is simply a string that can be calculated. 


This completes “Basics” in this chapter. You have learned how to: 


¢ Prompt, receive, and check user input 
e Manipulate variable templates 

¢ Use the period as a placeholder 

e Parse variables and expressions. 


“Advanced Topics” in this chapter discusses parsing using: 


e Literal-string patterns 
e Character positions 

¢ Variables in patterns 
e String functions. 


To continue with “Basics,” go to page 9-1. 
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Advanced Topics 
In this chapter: 


Advanced Topics 


Parsing with patterns 
Literal string patterns 


Character position 
Variables in patterns 
String functions. 


Parsing with Patterns 
By using patterns in a parsing template, you can have your programs analyze all 
types of information. In this chapter, several kinds of parsing patterns are discussed. 


For more information about the use of patterns refer to “Parsing” in the REXX 
Reference. 


Literal String Patterns 
One way to parse data is by literal pattern. If your PARSE instruction template 
specifies a literal string (one or more characters enclosed in quotes), the data being 
parsed is split at the point where the string is found. 


Figure 8-11 shows an example where the ARG instruction parses the data given with 
the command TAKE. The first literal pattern is the first / and the second literal 
pattern is the second /. 

/* Example: recognizing options */ 


arg drink form shelf "/" typl typ2 typ3 "/" rest 


say drink form shelf":" typl typ2 typ3 "(“rest")" 


Figure 8-11. TAKE.CMD 


The following is displayed on the screen. 


[C:\] take coffee beans /kenya decaf/in bags 
COFFEE BEANS : KENYA DECAF (IN BAGS) 


When the ARG instruction is processed: 


e¢ The words in front of the first pattern are parsed in the usual way into drink, 
form, and shelf. In this example, shelf is set to null; that is, an empty string or 
"" The SAY instruction keeps the space following the variable name. That is 
why there is a space before the colon. 


¢ The words between the first pattern and the second pattern (if there is one) are 
parsed into typl, typ2, and typ3. Here, typ3 is set to null, but SAY still displays 
the extra space before the parenthesis. 
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e If there isa second pattern, the words that follow it are assigned to the variable 
rest. In this example, rest is assigned the two-word string IN BAGS. 


This technique of parsing using literal patterns can be used with any of the parsing 
instructions. 


Character Position 


Absolute Position 


Relative Position 


Another way to parse a string is by the position of the individual characters. There 
are two types of positions, absolute and relative. 


Usually, the breaks in a parsed string occur at the spaces. For example: 
PARSE VALUE "Five golden rings" WITH varl var2 var3 


This instruction assigns: 


vari the string "Five". 
var2 the string "golden". 
var3 the string "rings". 


If you want to refer to the specific character position in the input string where you 
want the parsing to break, specify the number of characters from the beginning of 
the string. That is, the first character is 1, the second is 2, and so forth. 


PARSE VALUE "Five golden rings" WITH varl 10 var2 15 var3 


This template assigns: 


varl the string "Five gold" (up to the 9th position) 
var2 the string "en ri" (positions 10 to 14) 
var3 the string "ngs" (position 15 to the end) 


Figure 8-12 shows an example that uses PARSE VALUE to parse the string 
returned by REXX’s built-in TIMEQ function. The TIME(O string has two digits 
each for hours, minutes, and seconds that are separated by colons. For example, 
12:34:55. 


/* parsing TIME() by absolute character position */ 
PARSE VALUE time() WITH hr 3. 4m6./7 sc. 


say 'Hours :' hr 
say ‘Minutes :' mn 
say ‘Seconds :' sc 


Figure 8-12. ABSPTRN.CMD 


You can also specify breaks by relative position; that is, by a given number of 
characters from the last break. To parse this way, use signed numbers, which are 
numbers preceded by plus or minus signs to indicate the direction to move the break. 
For example: 


PARSE VALUE "Five golden rings" WITH varl 10 -5 var2 +8 var3 17 


This instruction assigns: 
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varl the string "Five gold" (up to the 10th position) 
var2 the string 'golden' (back 5, forward 8; note the leading space) 
var3 the string 'ring' (stopped at position 16) 


Figure 8-13 shows an example that uses PARSE VALUE as applied to the TIMEQ) 
string. 


/* parsing TIME() by relative character position */ 
PARSE VALUE time() WITH hr 3 +1 mn 6 +1 sc . 


say 'Hours ;:' hr 
say 'Minutes :' mn 
say ‘Seconds :' sc 


Figure 8-13. RELPTRN.CMD 


Though PARSE VALUE was used for these examples, you can use positional 
patterns with any PARSE instruction. 


Variables in Patterns 


To Summarize 


In place of a literal string or a position, you can use a variable containing the string, 
the absolute position, or the relative position. To do this, enclose the variable name 
in parentheses, as in Figure 8-14. 


char = ':' 

parse value time() with hr (char) mn (char) sc . 
say 'Hours :' hr 

say ‘Minutes :' mn 

say ‘Seconds :' sc 


Figure 8-14. VARPTRNI.CMD 


In fact, you can use a variable assigned in the same template, as in Figure 8-15. 


parse value time() with hr 3 char +1 mn (char) sc . 
say 'Hours :' hr 


say ‘Minutes :' mn 
say ‘Seconds :' sc 


Figure 8-15. VARPTRN2.CMD 


Any data can be parsed using patterns in the template of a PULL, ARG, or PARSE 
instruction. A token within a template is recognized as a pattern where there is: 


¢ A literal string, such as / in the example TAKE.CMD (see Figure 8-11) 
e A symbol in parentheses, which means that it is the name of a variable 


e An unsigned number, which means that parsing continues at the specified 
character position 


e A signed number, which means that parsing continues at the specified character 
position, relative to the first character of the last match. 
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String Functions 
Another kind of parsing can be performed using REXX’s built-in string functions. 
They are grouped here by the tasks they perform. For more information, refer to 
“Functions” in the REXX Reference. 


You can use the following functions to separate and change input strings. 


Getting Pieces 
Substring functions that get (return a piece of a larger string) are: 


SUBSTRO Gets a piece of a string by numbered position 


LEFTO Gets the leftmost substring; can add trailing spaces 
RIGHT(Q) Gets the rightmost substring; can add leading spaces 
WORDO Gets a word from a string (by number) 


SUBWORDQ _ Gets a substring beginning with a given word. 


Editing 
Functions that change a string are: 
INSERTQO Inserts a substring into a string 
OVERLAYQ(Q = _ Overlays part of one string with another 
REVERSEOQ Swaps the characters in a string, end for end 
COPIESQO Replicates a string a given number of times. 
Deleting 
Functions that delete substrings are: 
DELSTRO Deletes a substring fromthe input string 
DELWORDQO Deletes a substring from the input string, beginning with a given 
word. 
Formatting 
Functions that change a string by adding or removing spaces or other characters are: 
SPACE(Q) Adds or deletes intervening spaces (or other delimiting characters) 
between words 
CENTERQ Centers the input string within a larger string of a given length; 
adds spaces (or other characters) 
STRIPO Removes leading or trailing spaces (or both) from a string. 
Note: The previously described LEFT and RIGHT functions can also add spaces. 
Counting 


Functions that get the lengths of strings, compare strings, or locate a particular 
character position within a string are: 


LENGTHO Counts the characters in a string 
WORDSQ Counts the words in a string 
WORDLENGTHO _ Returns the length of a word (specified by number). 
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Comparing 
Functions that return a number, based on a comparison of two strings are: 


VERIFYQ Determines whether one string is made up of characters in another. 
It can return the position of either the first matching character or 
the first nonmatching character (the default). 


ABBREVQ Returns 1 (true) if one string matches the leading characters of 
another. 


COMPAREQ __ Determines if two strings are identical. 
Finding Positions 
Functions that return a number that is a sought-after character position are: 


POSO Searches one string, from the beginning, for the presence of a 
given substring and returns the substring’s position 


LASTPOSO Searches one string, from the end, backward, for the presence 
of a given substring and returns the substring’s position 


WORDINDEXO Searches for a word by number and returns the initial 
character position 


WORDPOSO Seaches for a word by the word itself and returns the initial 
character position. 
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Examples 
Figure 8-16 shows an example of a REXX program that may be called as a string 
function. It changes an input number into a string in currency format. It uses 
PARSE VAR with a literal pattern and PARSE VALUE with a character-position 
pattern. 


/* Takes a number and returns a string in comma-delimited 
/* dollar format; e.g., DOLLAR(1234.5555) returns '$1,234.56' 


arg number /* get the argument NUMBER 


/* Round off the argument to the nearest cent, then i 
/* parse the result into the integer (DOLLARS), the */ 
/* decimal point and the decimal fraction (CENTS) */ 
/* (NOTE: More about the FORMAT() function on page 9-6.) */ 


PARSE VALUE format (number, ,2,0) WITH dollars "." cents 
dollars = abs(dollars) /* make DOLLARS positive 


backin = reverse(dollars) reverse the digits in 
DOLLARS so we can parse 
them into groups of 3 
(see REVERSE(), above) 


backout = "" initialize a variable 
for re-concatenation 


do while length(backin) > 3 /* while three digits or 

more remain in BACKIN, 

PARSE VAR backin group 4 backin /* take each group of three 
remaining digits, and 

backout = backout}!group}/"," /* then join it to the end 
of the BACKOUT variable 
and add a comma 

end 


backout = backout}!backin| }"$" concatenate the digits 
that remain; add '$' 


if number < @ then /* if the argument was 
backout = backout}{/"-" negative, restore the 
minus sign 
bucks = reverse(backout)}{/"."} {cents restore the proper order 
of the digits; add the 
decimal point and cents 


return bucks return the string 


Figure 8-16. DOLLAR.CMD 
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Figure 8-17 shows an example of how DOLLAR.CMD could be used as a function 
in the program SUM.CMD (see Figure 6-10). 


/* using the function DOLLAR() in a program */ 
total = 0 
do forever 

say "Type amount:" 

pull entry 


if \datatype(entry,n) /*if entry is not a valid number */ 
then leave /* leave the loop */ 
total = total + entry 
say "Total = " DOLLAR(total) /* display TOTAL in dollar format */ 
end 
say entry "is not a number. Returning to 0S/2." 


Figure 8-17. SUMCASH.CMD 


Figure 8-18 shows an example of a useful search-and-replace string function. Notice 
how the second PARSE instruction uses a variable as a pattern. 


Function: CHANGE(string,old,new) 

Changes all occurrences of "old" in "string" 

to "new". If "old" == "", then "new" is prefixed 
to "string". 


parse arg string, old, new 
if old=="" then return new] |!string 


out="" 

do while pos(old,string)\= 0 
PARSE VAR string prepart (old) string 
out=out} | prepart} {new 

end 

return out} |string 


Figure 8-18. CHANGE.CMD 
Figure 8-19 shows an example using the CHANGE() function. 
/* using the CHANGE() function */ 


direction = "north by northwest” 
wrong = "north" 


right = "south" 
say direction 
say change(direction,wrong,right) /* displays "south by southwest" */ 


Figure 8-19. CHNGDEMO.CMD 
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Chapter 9. Arithmetic 


This chapter discusses using REXX for calculating and displaying numbers. For 
more detailed information, refer to the REXX Reference. 


Tn 


Basics 
In this chapter: 
Basics 


About REXX numbers 
Checking input numbers 
Calculating 

Formatting output. 


> 
> 
> 
> 


About REXX Numbers 
Character strings on which REXX can perform arithmetic operations are referred to 
as numbers. 


In REXX, a number is a string of digits (0 through 9). A number must begin with a 
digit, a plus sign (+), or a minus sign (—). A single decimal point is permitted. The 
letter E (or e) can be used to denote powers of 10. 


The NUMERIC DIGITS instruction controls the number of decimal places allowed. 
The default is nine places. 


REXX ignores leading and trailing spaces in number strings. It does not allow 
spaces or commas within a number. 


These are some examples of valid REXX numbers: 


12 This is a whole number or integer. 
—5 This is a signed number (minus five). 
0.5 This is a decimal fraction or decimal (one half). 


3.5E6 This is a floating point number (three and one-half million). It uses 
exponential notation. This notation is useful when dealing with very large 
or very small numbers. The portion that follows the E is the number of 
places the decimal point must be moved to the right to make it into an 
ordinary number. | 


Checking Input Numbers 
: Before a program tries to do arithmetic on data typed from the keyboard, the data 
should be checked to verify that it has valid numbers to work with. You can do this 
by using the DATATYPEO function. For example: 


datatype(expression,[type]) 
where 
expression is the value to be tested. 


type is an optional argument, the kind of data you are testing for. 
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In its simplest form, DATATYPED( returns the string NUM if the argument (the 
expression inside the parentheses) is accepted by REXX as a number that could be 
used in arithmetical operations. Otherwise, it returns the string CHAR. 


The value of is the string 
datatype (49) "NUM" 
datatype(5.5) "NUM" 
datatype(5.5.5) "CHAR" 
datatype("5,000") "CHAR" 
datatype(5 4 3 2) "CHAR" 


Figure 9-1 shows an example that requires the user to keep trying until a valid 
number is typed. 


/* Example requiring numeric input */ 
do until datatype(howmuch) = "NUM" 
say "Type a number" 
pull howmuch | 
if datatype(howmuch) = "CHAR" then 
say "That was not a number. Try again!" 
end 


say "The number you typed was" howmuch 


Figure 9-1. VALNUM.CMD 
To test for a particular type of data, such as whole numbers, use the alternative form 
of the DATATYPEO function. This form requires two arguments: 

¢ The expression to be tested 

¢ The type of data to be tested; for example, whole for a whole number. 


Only the first character of type is inspected. To test for whole numbers, it 
would be sufficient to write W or w. In this book, whole is used to remind you of 
the meaning of this argument. 


This form of the function, DATATYPE(number,whole), returns 1 (true) if number is a 
whole number, 0 (false) if otherwise. For example: 
do until datatype (howmany,whole) 

pull howmany 


end 


If you also want to restrict the input to numbers greater than 0, you could write: 


do until datatype(howmany,whole) & howmany > 0 


pull howmany 


° 
» 
e 


end 
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Calculating 


The ampersand (&) is an operator that combines conditions (see “Combining 
Expressions” on page 4-6). In this example, both datatype (howmany whole) and 
howmany > 0 must be true for the loop to end. 


The DATATYPE( function can test for other types of data, as well. For examples, 
see the REXX Reference. 


Addition and Subtraction 
These operations are performed in the usual way. You can use both whole numbers 


and decimal fractions. 


Operator 


+ (plus sign) 
— (minus sign) 


Multiplication and Powers 


Division 


Operator 


* (asterisk) 
** (double asterisk) 


Operation Example 

Add say 7 +2 /* displays '9' */ 
Subtract say 7 —2 /* displays '5' */ 
Operation Example 

Multiply say 7* 2 /* displays '14' */ 
Raise to a whole say 7**2 /* displays '49' */ 


number power 


When you divide, you determine whether or not you want the answer expressed as a 
whole number (integer). The operators you can use are: 


/ (one slash) 


% (percent sign) 


// (two slashes) 


Divide. For example: 
say 7/2 /* displays '3.5' */ 


Integer divide. The result is a whole number. Any remainder 
is ignored. For example: 


say 7%2 /* displays '3' */ 
Remainder after integer division. For example: 
say 7 // 2 /* displays '1' */ 
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Notice which of these operators is used in the example shown in Figure 9-2. 


This program works out how to share zero or more 
sweets between one or more children, assuming that 
a single sweet cannot be split. 


until datatype(sweets,whole) & sweets >= 0 
say “How many sweets?" 
pull sweets 

end 


do until datatype(children,whole) & children > 0 
say "How many children?" 
pull children 


say “Each child will get" sweets%children "sweets", 
"and there will be" sweets//children "left over." 


Figure 9-2. SHARE.CMD 


Do not to try to divide by 0. If you do, a syntax error results. That is why, in 
Figure 9-2, the user was not allowed to answer 0 to the question “How many 
children?”. 


Because apples and oranges can be cut into pieces, you can use the / division 
operator. For example: 

children = 5; apples = 7; 

say "Each child gets" apples/children "apples." 

/* displays 'Each child gets 1.4 apples.' */ 

Fractions are usually computed with an accuracy of nine significant digits. For 
example: 

children = 3; oranges = 7; 


say "Each child gets" oranges/children "oranges." 


/* displays 'Each child gets 2.33333333 oranges.' */ 


To summarize: 
¢ The result of a % operation is always a whole number, the quotient only. 


¢ There may be a remainder. To compute the remainder, write the expression 
using the // operator. 


¢ The result of a / operation can be a decimal. 
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Range and Precision 
REXX calculates the result correct to nine digits if necessary. This means nine 
significant digits, not counting the zeros that come immediately after the decimal 
point in very small decimal fractions. For example: 


say 1*2*3*4*5*6*7*8*9*10*11*12 /* displays '479001600' */ 
say 7/30000000000 /* displays '@.000000000233333333' */ 


The accuracy of computed results can be changed using the NUMERIC DIGITS 
instruction. See “Changing Precision” on page 9-16. 


Exponential Notation 
Numbers much larger or smaller than those previously discussed are difficult to read 
and write, because it is easy to make a mistake counting the zeros. It is simpler to 
use exponential notation. Very large numbers can be written as an ordinary number, 
followed by a letter E, followed by a whole number, called the exponent. The 
exponent is how many places to the right (positive exponent) or left (negative 
exponent) that the decimal point of the fixed-point number would have to be moved 
to obtain the same value as an ordinary number. For example: 


4.5E6 is the same as 4 500 000 (four and one-half million) 
23E6 is the same as 23 000 000 (twenty-three million) 

1E12 is the same as 1 000 000 000 000 (a million million) 
4.5E—3 is the same as 0.004 5 (four and one-half thousandths) 
1E—6 is the same as 0.000 001 (one millionth). 


Write numbers this way in expressions and also when entering numeric data 
requested by REXX programs. REXX uses this notation when displaying results 
that are too large or too small to be expressed conveniently as ordinary numbers or 
decimals. When REXX uses this notation, the part of the number that comes before 
the E (the mantissa) is usually a number between 1 and 9.999 999 99. For example: 


j=l 

do until j > lel2 
say j /* displays '1' */ 
jej* ll /* ‘qi! */ 
end /* "121! */ 
* "1331! */ 
/* "14641! */ 
/* '161051' */ 
/* "1771561! */ 
/* '19487171' */ 
/* '214358881' sa § 
/* '2.35794769E+9' = */ 
[* '2.59374246E+10' = */ 
| is '2.85311671E+11' */ 


Numbers written in exponential notation, such as 1.5E9, are sometimes called 
floating-point numbers. Conversely, ordinary numbers, such as 3.14, are sometimes 
called fixed-point numbers. 
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Test Yourself 
What is displayed on the screen when you run the program shown in Figure 9-3? 


/* Example: arithmetical operations */ 
quarter = 25 

deuce = 2 

say quarter + deuce 

say quarter - deuce 

say quarter * deuce 


say quarter / deuce 
say quarter % deuce 
say quarter // deuce 
xX = quarter"E"deuce 
say x + 0 


Figure 9-3. ARITHOPS.CMD 


Answer: The following is displayed on the screen. 


[C:\] arithops 
27 


The last two lines of the program require some explanation. First, x gets the value 
25E2. This is the same as 25.00 with the decimal point moved two places to the 
right (in other words, 2500). When x is used in the arithmetical expression, the 
number 25E2 is added to 0, giving a result of 2500. 


Formatting Output 
Your program has accepted numbers from its user and made calculations. Now it 
must display the results. 


When formatting output, REXX: 


e Rounds numbers automatically before every operation, if necessary. Rounding 
is to the current precision value set by a NUMERIC DIGITS instruction (see 
page 9-16) or to the default value of nine decimal digits. 


¢ Removes all leading zeros from the integer part of number, but leaves in the 
trailing zeros in the decimal portion. 
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You may want to keep the precision of the calculations to the ninth place, but you 
do not need to display all those extra zeros. That is what the following two 
functions are for: 


TRUNC (number, places) 


TRUNCO returns just the integer part of number and the number of decimal places 
you specify. The only remaining decimals are truncated or cut off. That is, TRUNC 
rounds down. For example: 


say trunc(321.765,2) /* displays 321.76. */ 


Likewise, FORMATO function leaves a specified number of decimals, but it does 
conventional rounding. The last decimal remaining is increased by one if the next 
(truncated) decimal is 5 or greater. For example: 


FORMAT (number, before, after) 


The first three arguments of the FORMATO function are: 


The number to be formatted 
How many digits to be shown before the decimal point 
How many digits to be shown after the decimal point. 


For example: 
say format (321.765,3,2) /* displays 321.77 */ 


Note: 321.7649 rounded to two places is 321.76, because FORMATO only uses the 
first truncated digit to determine rounding. 


Figure 9-4 shows an extended example to compare FORMAT( and TRUNC(O. 


/* An example of rounding and displaying numbers *] 
say 

say " At full Round w/ Round w/ " 
say “ precision FORMAT() TRUNC()" 

say copies("-",45) 


do num = 1 to 9 
quotient = 23 / num 


norm = FORMAT(quotient,3,3) /* rounding normally to 3 decimal places */ 
down = TRUNC(quotient,3) /* rounding down to 3 decimal places */, 


/* Now, we will use FORMAT() to put the numbers into columns */ 


say "23/"num "=" FORMAT(quotient,2,8) FORMAT(norm,6,3) FORMAT (down, 6,3) 


Figure 9-4. ROUNDING.CMD 
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The following is displayed on the screen, when you run ROUNDIT.CMD. 


[C:\]roundit 


At full Round w/ = Round w/ 
precision TRUNC() 


23/1 = 23.00000000 
23/2 = 11.50000000 
23/3 = 7.66666667 
23/4 = 5.75000000 
23/5 = 4.60000000 
23/6 = 3.83333333 
23/7 = 3.28571429 
23/8 = 2.87500000 
23/9 = 2.55555556 
[c:\] 


Summary 
This completes “Basics” in this chapter. You have learned how to: 


e¢ Check user input 
¢ Make REXX do the calculating 
¢ Display the results on the screen. 


“Advanced Topics” in this chapter discusses: 


e Additional formatting techniques 

¢ How to control the precision of REXX arithmetic 
e¢ Comparing number strings 

¢ Scientific notation and exponentiation. 


To continue with “Basics,” go to page 10-1. 
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Advanced Topics 
In this chapter: 


Advanced Topics 


Putting numbers into columns 
Formatting errors 

Rounding errors 

Conventional and scientific notation 


Changing precision 
Comparing numbers 
Powers (** operator) 
A square-root function. 


vvvvrvvyvy 


Putting Numbers into Columns 
Columns of figures are easier to read if the numbers are aligned with the units in the 
same column. The FORMAT( function helps you to do this (see Figure 9-5). 


/* Example showing how columns of figures are formatted */ 


0.733 
1995; 
70000; 
400/12; 


101; unitprice.1 
500; unitprice.2 
60000; unitprice.3 
500; unitprice.4 


qty.1 
qty.2 
qty.3 
qty.4 


Hou ot 


say “Quantity Unit Price Total Price Observations" 


do item = 1 to 4 
say format(qty.item, 5,0), 
format (unitprice.item, 11,2), 
format(qty.item * unitprice.item, 12,2), 
"" remark. item 


Figure 9-5. INVOICE.CMD 


The following formatted data is displayed on the screen. 


Quantity Unit Price Total Price Observations 
101 0.73 73.73 OK 


500 1995 .00 997500 .00 OK 
60000 70000 .00 4. 20E+9 OK 
500 33.33 16666.67 OK 


Formatting Errors 
The numbers to be formatted should always be small enough to fit into the space 
you have reserved for them with FORMAT. 


A simple rule is to always specify at least nine spaces for the before the decimal point 
argument. To ensure that numbers with more than nine digits are displayed in 
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exponential notation. The extra characters required causes fields to the right of the 
number to shift to the right, thus drawing attention to the exception. 


Look at item 3 in the previous example. The quantity times the unit price (60 000 
times 70 000) gives a total price of 4 200 000 000, which is too large for the 
nine-digit field that was specified. The result has therefore been displayed in 
exponential notation. This in turn has caused OK to be shifted right. 


If we add qty.5 = 880 000, unitprice.5 = 1, and remark.5 = "Big deal" and 
change the 4 to a 5 in the DO instruction, then the following is displayed on the 
screen. 


[C:\]Jinvoice 
Quantity Unit Price Total Price Observations 
101 0.73 73.73 OK 
500 1995.00 997500 .00 OK 
60000 70000.00 4.20E+9 OK 
500 33.33 16666 .67 OK 


12 +++ say format(qty.item, 5,0), format(unitprice.item, 11, 2), 
format (qty.item * unitprice.item, 12,2), " " remark. item 
REX0040: Error 40 running C:\INVOICE.CMD, line 12: Incorrect call to 
routine 


[C:\] 


The error could have been avoided by: 
¢ Testing the input values for a maximum number of 99 999 
or 
e Allowing space enough for at least nine digits for the integer part. For example: 


say format(qty.item, 9,0), 
format (unitprice.item, 9,2), 
format (qty.item * unitprice.item, 11,2), 
"" remark. item 


The following formatted data is displayed on the screen. 


Quantity Unit Price Total Price Observations 
101 0.73 73.73 OK 
500 1995.00 997500 .00 OK 


60000 70000 .00 4.20E+9 OK 
500 33.33 16666.67 OK 
880000 1.00 880000.00 Big deal 
[c:\] 


Rounding Errors 
When your program performs a series of arithmetical operations, additional errors 
can be inadvertently introduced. Look at the fourth item in the INVOICE.CMD 
program shown in Figure 9-5 on page 9-9. The customer seems to have been 
overcharged by $1.67. The price was $400 a dozen. FORMATO has rounded this 
to 33.33 each. But Total Price was not rounded until after it had been multiplied 
by 500. 
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For rounding numbers, use FORMATO at the point in your calculations where you 
want rounding to occur. For rounding down, use TRUNC(. 


Test Yourself 
Write a program that accepts input liquid quantities and unit prices and displays the 
price per gallon and per liter. 


Answer: Figure 9-6 shows an example, divided into six parts, of one way to do 
this. 


/* Calculate a conversion table for input liquid quantities 


Simple variables (input and program control): 
INPUTQTY : Quantity 

INPUTUPR : Unit price 

UNIT : Unit of measure (G or L) 

RPTUPR : Unit price of previous entry 

RPTUNIT : Unit of measurement of previous entry 
ITEM : Item number (each purchase) 


Compound symbols (for each item of output): 
QTYINGAL. ITEM : Quantity in gallons 
UPPGAL. ITEM : Unit price per gallon 
QTYINLIT.ITEM : Quantity in liters 

UPPLIT. ITEM : Unit price per liter 
TTLPRC. ITEM : Total price of purchase 


/* MAIN PROGRAM: Calls input subroutines GETQTY, GETUPR, and GETUNIT 
/* and CALCULATE subroutine ; results are then displayed in table. 


inputqty = "" /* Initialize variable for quantity input 
/* (also controls end of input). 


do item = 1 /* For each item... 


call getqty /* - get input for quantity 
if inputqty = "" then if none entered, then quit the loop 
leave and display results 


call getupr - get input for unit price 

call getunit - get unit of measurement for input 
call calculate /* - do the calculations 

inputqty = "" /* re-initialize input variable 


/* and repeat the loop 


Figure 9-6 (Part 1 of 6). LIQUID.CMD 
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/* When all data have been input, display a header 
say 
say" | IN LITERS 
say " ' quantity unit 
say" | price 
say copies ("=",56) 
/* ... then display the calculated values in columns using FORMAT(). 
last = item -1 
do item = 1 to last 

Say, 


IN GALLONS TOTAL" 


| quantity unit } PRICE" 
price | : 


format (item,3,0)" |", /* Item number 
format (qtyinlit.item,5,2), /* Qty. in liters 
format (upplit.item,3,3)" ;", /* Price per liter 
format (qtyingal.item,5,2), /* Qty. in gallons 
format (uppgal. item,3,3) " ; /* Price per gallon 
format (ttlprc.item,7,2) /* Total purchase 


Figure 9-6 (Part 2 of 6). LIQUID.CMD 


/* Following are the subroutines for data input 


getqty: /* Accept input quantity for each item. 
/* The DO loop allows the user to type only a number or (by 
/* pressing the Enter key alone) a null string, ending the input loop.*/ 


do until datatype(inputqty,n) | inputqty = "" 
say 
say "Type quantity for item number" item 
say " or press the Enter key alone to end the program." 
pull inputqty 
end 


return 


Figure 9-6 (Part 3 of 6). LIQUID.CMD 


9-12 REXX User’s Guide 


getupr: /* Accept input for each item's unit price. 
The SYMBOL() function tests whether previous input exists 
(i.e., if the variable REPTUPR has been assigned a value). 
If so, the user can ‘carry over' that previous input by 
simply pressing the Enter key. 


say "Type unit price" 
if symbol("reptupr") <> "LIT" then 
say " (or press the Enter key for" reptupr")" 


/* Again, the DO loop allows only numeric input. 


do until datatype(inputupr,n) 
pull inputupr /* Entering a null string (i.e., 
if inputupr = "" then /* pressing the Enter key only) 
inputupr = reptupr /* ‘carries over' the previous item's 
else reptupr = inputupr /* unit price; otherwise this input is 
end /* stored for later ‘carry-over. ' 
return 


Figure 9-6 (Part 4 of 6). LIQUID.CMD 
getunit: /* Accept input for measure (liters or gallons); 
/* again, the SYMBOL function checks for prior use of repeat variable 
say "Type G for gallons or L for liters" 
if symbol("reptunit") <> "LIT" then 


say " (or press the Enter key for" reptunit")" 


/* The DO loop allows only a "G" or "L" as input 


do until unit = "G" } unit = "L" 
pull unit 
if unit = "" then /* A null string is changed to 
unit = reptunit /* the previous input; otherwise 
else reptunit = unit /* this entry is stored for next time. 
end 


return 


Figure 9-6 (Part 5 of 6). LIQUID.CMD 
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calculate: /* Calculate the output values according to unit 


select 

when unit ="G" then do /* if input is in gallons... 
qtyingal.item = inputqty store the input quantity 
qtyinlit.item = inputqty*3.7853 /* convert to liters 
uppgal. item inputupr /* store the unit price 
upplit.item inputupr/3.7853 * compute 'per liter’ price 
end 

when unit ="L" then do /* if input is in liters... 
qtyinlit.item = inputqty /* store the input quantity 
qtyingal.item = inputqty/3.7853 /* convert to gallons 
upplit.item = inputupr store the unit price 
uppgal.item = inputupr*3.7853 compute 'per gallon' price */ 
end 


end 


ttlprc.item = inputqty * inputupr compute total price of item */ 
return 


Figure 9-6 (Part 6 of 6). LIQUID.CMD 


Conventional and Scientific Notation 
You can control whether numbers are expressed in conventional or scientific 
notation with the FORMATO(O function. 


Fixed-point (Conventional) Notation 
To stop FORMATO from returning floating-point numbers (when results would 
usually be expressed in floating-point numbers), use the fourth argument of 
FORMAT. This argument specifies the number of character positions reserved for 
the exponent. Exponential notation is not used if you write: 


FORMAT (number, before, after ,0) 


Be sure that the amount of space you have allowed for before and after is 
sufficient. 


Floating-point (Scientific) Notation 
To make FORMATQ( return floating-point numbers (called exponential or scientific 
notation) when the results would usually be expressed in fixed-point numbers, use 
the fifth argument of FORMATO(Q. This argument specifies the threshold for 
expressing the result in exponential notation. Exponential notation is used if you 
write: 
FORMAT (number, before, after, ,0) 


Note: When a floating-point number has an absolute value between 1 and 
9.999 999 99 (that is, when the exponent is 0) the characters E+0 are always 
omitted, even when floating-point has been specified. 


For other uses of the FORMAT( function, see the REXX Reference. 
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Test Yourself 


1. Write a program called REFORMAT that expresses numbers typed by the user 
in both fixed-point and exponential notation. 


2. Test your program with the numbers: 


123 456 789 

0.000 000 000 001 234 5 
999 999 999 999e-6 
1.2e10 

L2 

1.2e+0 


Answers: 


1. Figure 9-7 shows an example of a possible answer. 


/* Example: to change the format of a number */ 
do forever 
say "Type a number" 


pull answer 

if \ datatype(answer,number) then exit 

say "Fixed-point equivalent:" format (answer, , ,0) 
say "Exponential equivalent:" format (answer,,, ,0) 


Figure 9-7. REFORMAT.CMD 


2. Figure 9-8 shows a table that lists the results you should get when using the test 
numbers with the REFORMAT.CMD. 


1.2e+0 


Figure 9-8. REFORMAT.CMD Results 
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Changing Precision 
If you want to avoid using exponential notation, or if you want to control the 
precision of your calculations, use the NUMERIC DIGITS instruction to change the 
number of significant digits (see Figure 9-9). (The default setting for NUMERIC 
DIGITS is 9.) 


/* examples of numbers with unusually high precision */ 


numeric digits 10 

say "The largest signed number that can be held" 
say "in a C long integer is" 2**31 - 1 "exactly." 
say 


numeric digits 48 
say "1/7 =" 1/7 


Figure 9-9. ACCURATE.CMD 


The following is displayed on the screen when you run the program. 


[C:\] accurate . 
The largest signed number that can be held 
in aC long integer is 2147483647 exactly. 


1/7 = 0.142857142857142857142857142857142857142857142857 
[C:\] 


To check the current setting of the NUMERIC DIGITS instruction, use the 
DIGITSQ function, digits(). If you have not used the NUMERIC DIGITS 
instruction to change precision, then the DIGITS(Q function returns 9 (the default 
setting). 


Rounding and Precision 
The NUMERIC DIGITS instruction specifies the maximum number of significant 
digits in the result of a REXX calculation. Whatever the setting you give for 
NUMERIC DIGITS, REXX carries out its calculations to an even higher precision. 
Extra guard digits are provided for each input number. Multiplication and division 
are calculated out to twice the NUMERIC DIGITS setting. 


This means that the only arithmetic errors that can occur are in the final rounding. 
For example: 


numeric digits 3 
say 100.3 + 100.3 /* displays 201 sf 
/* 200.6 is rounded to '201' ot | 


Unless you have a specific need for high-precision calculations, leave NUMERIC 

DIGITS at the default setting of 9. Higher settings can slow your programs down 
needlessly. Lower settings can affect calculations in a way you do not intend (for 

example, how DO loop counters are incremented). When you need to round final 
results for printouts or displays, use the FORMAT(O function. 


For more information about rounding, see “Numerics and Arithmetic” in the REXX 
Reference. 


9-16 REXX User’s Guide 


Comparing Numbers 
There are times when an accurate comparison is inconvenient (see Figure 9-10). 


/* Example: no approximation here */ 


say 1 + 1/3 /* displays '1.33333333' */ 
say 1 + 1/3 + 1/3 + 1/3 /* displays '1.99999999' = */ 
say 1 + 1/3 + 1/3 + 1/3 = 2 /* displays '0' (false) */ 


Figure 9-10. NOFUZZ.CMD 


To make REXX comparisons allow for approximate values (make them less accurate 
than ordinary REXX arithmetic), use the instruction, NUMERIC FUZZ n, where n is the 
number of digits (at full precision) that REXX should ignore when comparing 
numbers. The number n must be a whole positive number (or any expression that is 
so evaluated), and it must be less than the current NUMERIC DIGITS setting (see 
Figure 9-11). 


/* Example: allowing approximation */ 
say 1 + 1/3 + 1/3 + 1/3 = 2 /* displays '0' (false) */ 


numeric fuzz 1 
say 1 + 1/3 + 1/3 + 1/3 = 2 /* displays '1' (true) */ 


Figure 9-11. FUZZ.CMD 


To check the current setting of the NUMERIC FUZZ instruction, use the function, 
FUZZ(). If no NUMERIC FUZZ setting has been given, FUZZ() returns 0 by 
default. This means that the 0 digits are ignored during a comparison operation. 


Powers (** Operator) 
The operator ** means raised to the whole-number power of. For example: 


2**1 = 2 = 2 (2 to the power of 1) 
2**2 = 2*2 = 4 (2 to the power of 2, or 2 squared) 
2**3 = 2*2"*2 = 8 (2 to the power of 3, or 2 cubed) 


2**4 = 2*2*2*2 16 (2 to the power of 4). 


As in ordinary algebra: 


2**0 = 1 
2*#_] = 1/(2**1) = 0.5 (2 to the power of minus 1) 
2**_2 = 1/(2**2) = 0.25 (2 to the power of minus 2). 


Note: The number on the right of the ** must be a whole number. 


In the order of precedence built into REXX, the powers (**) operator comes below 
the prefix operators and above the multiply and divide operators. For example: 


say —5**2 /* displays '25'. Same as (—5)**2 +7 
say 10**3/2**2 /* displays ‘250°. Same as (10**3) /(2**2) */ 
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Test Yourself 
1. Examine the program shown in Figure 9-12. 


/* Example of a negative exponent */ 


if 2 ** -3 = 1/(2**3) then say "True" 
else say "False" 


Figure 9-12. EXPONENT.CMD 
a. What is displayed on the screen when you run this program? 
b. Are the parentheses in this expression really necessary? 


2. What value is computed for the expression: 
say 9 ** (1/2) 


Answers 
1. In EXPONENT.CMD 


a. The word True is displayed on the screen. 
b. No. The ** operator has a higher priority than the / operator, so REXX 
evaluates the expression in the same way if the parentheses were removed. 


2. The result is a syntax error. The decimal form (9 ** 0.5) does not work either. 
True, in mathematics, x to the power of 1/2 means the square root of x. But in 
REXX, the ** operator must be followed by a whole number or by an 
expression that, when evaluated, gives a whole number. 
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A Square-Root Function 
Figure 9-13 shows an example of a SQRT(Q function written as a REXX program. 


The SQUARE ROOT function 


SQRT (number) 


where "number" is a non-negative REXX number, 
/* returns the square root of "number". Precision is */ 
/* nine significant figures, independent of the setting */ 
of NUMERIC DIGITS (explained on page 9-16). */ 


/* Implementation details: "number" is normalized to 
/* give an even exponent (so that the exponent can be */ 
/* dealt with separately later) and a mantissa between A 
/* 1 and 100. The most significant digit of the result */ 
is found. */ 


The mantissa is multiplied by 100, the exponent is 
/* reduced by 2 to compensate, the partial result 


/* (ROOT) is multiplied by 10 (leaving a Q in the */ 
/* units position) and the units digit of this partial */ 
result is then found, and so on. */ 


Finally, the result is adjusted using the computed 
exponent. 


for partial results 
/* use one digit more ff 
than final precision 


if arg() \= 1 


then return /* wrong number arguments */ 
arg X 
if \ datatype(x,number) 

then return /* argument not a number */ 
if x <0 

then return /* argument is negative */ 


/* continued ... 


Figure 9-13 (Part 1 of 2). SQRT.CMD 
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/* Normalize: 
/* FROM 
[PX the argument 
/* COMPUTE 
mant the mantissa, where 0 < mant < 100 
the exponent, where exp is even 


/* Format so that 0 < mant < 10 
parse value format(x,,,,0) with mant "E" exp 


/* Modify so that exp is even 
if exp = "" then exp = 0 
if exp//2 \= @ then do 
mant = mant * 10 


do digit = 9 by -1 to 0, /* find largest digit, */ 

while, /* such that +) 

(root + digit)**2 > mant /* (root+digit)squared */ 
[> is \> mant*/ 


end 
root = root + digit 

if root**2 = mant then leave 
root = root * 10 

mant = mant * 100 


numeric digits 9 
return root * 10**(exp/2) 


Figure 9-13 (Part 2 of 2). SQRT.CMD 
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Chapter 10. Input and Output 


REXX can do more than manipulate the information that the user has typed at the 
keyboard and then process it for display on the screen. REXX can store, access, 
print, and organize data outside the program. 


Basics 
In this chapter: 
Basics 


A stream of information 


Text file processing 
Writing data to a file 
Reading data from a file 
Printing a text file. 


A Stream of Information 
In computing, the form in which information comes is often as important as its 
content. A spreadsheet file, for example, contains not only the numbers and 
formulas put into it, but a good deal of other information that you never see, such 
as information about the structure of the file. This additional data describes how 
the file is organized and how it is stored and displayed. 


The structure of a spreadsheet file is very different from that of a document 
formatted by a word processor. Information takes on other forms when it moves 
among the various devices in a system: the keyboard, the display, the printer, and so 
on. 


The goal of the REXX language is to keep things as simple as possible. Therefore, 
REXX takes the simplest possible view of the information it receives. The simplest 
way to look at information is one character at a time. REXX< sees external 
information as a stream, a long, single-file row of characters. 
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For example, in a REXX program that reads from a text file and then sends the text 
to a printer, both the file and the device to which the printer is connected are 
character streams: 


Input stream. JAB. TXT 


text file 
(JAB. TXT) 


a REXX 
program |——slithy—toves—did-gyre—and... 
Twas—bril1ig—and-the 


printer 
(PRT) 


Output stream PRT 


In the preceding diagram: 


¢ The text file being read (JAB.TXT) is the input stream. 
¢ The printer device written to (PRT) is the output stream. 


In this discussion, a stream means any source or destination of external information 
used by a REXX program. A stream can be a disk file, the input from the keyboard 
or a data port, or the output to a printer or display. 


In certain instances, as with text files, REXX can work with a stream in entire lines 
of data; that is, as strings of characters separated by carriage returns. For example: 


lines 


-line 1—~> 

line2————> 

Tine3—————> 

—line4——~> 

Twas brillig®And the slithy tovesedid gyre and gimble@in the wabeeal] mi 


carriage returns 


REXX can arrange these lines into ordered lists, called queues. 


The input and output operations of REXX fall into these broad categories: 


¢ Streams of characters 
¢ Lines, or segments of a stream, separated by carriage returns 
¢ Queues, which are ordered lists of lines. 


The way you use data streams in a program depends upon the kind of information 
you are working with and what you want to do with it. 
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Text File Processing 


LINEOUT() Function 


Calling LINEOUT() 


You begin text file processing by putting line data into more or less permanent form, 
such as in simple text files on disk. You already know some ways to create, read, 
and write disk files, either through application programs, such as your text editor, or 
through the OS/2 program. 


In REXX, file processing is performed with a set of stream functions that read and 
write data a single character at a time or line-by-line. Because text files are usually 
organized into lines, the first function you try is one that writes in lines. 


To write a line of text to a file, use the LINEOUTQO function. For example: 
lineout (stream, 1] inedata) 
where: 


stream is name of the file (that REXX regards as a stream) to which the text is 
written. 


linedata is a line of text (or any data) to be written. 


The first time a program uses LINEOUTO( in this way, the named stream is opened 
for writing and the line linedata is written to the end of the stream. 


The stream remains open, and each subsequent LINEOUTO( call writes a new line to 
the end of stream. 


When the program ends, REXX automatically closes stream. Or, you can close 
stream explicitly at any time by omitting the linedata argument. For example: 


lineout (stream) 


LINEOUTO is a function call rather than a keyword instruction. That means that it 
not only performs a given task (writing data to a file, in this example), but that it 
also returns a value of: 


e @Qif linedata was successfully written to stream. 
° 1if for any reason linedata could not be written. For example, if you try to 
write to a read-only file. 
The return value can be used by your program to detect whether something has gone 
wrong in the course of writing to a stream. 
Note: If you use LINEOUT( without the linedata argument, the return value tells 
you if stream was successfully closed. 
LINEOUT( is a function call; therefore, you have a choice about how you can use 
it. You can call LINEOUT: 
e As part of a REXX instruction. For example, with the keyword SAY: 
say lineout("mybook.txt","Chapter 1.") /* displays "0" if successful */ 
or as a variable assignment: 


ready = lineout("mybook.txt", "Chapter 1.") /* assigns "0" to READY *f 
/* if successful *} 
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e As a subroutine with arguments (this is true of all function calls). For example: 


call lineout “mybook.txt", "Chapter 1." 


When you use LINEOUT(O (or any function call) in this way, the return value of the 
function is automatically assigned to the REXX variable RESULT. For more 
information about calling functions in this way, see “Using a Call of the Other 
Kind” on page 7-13. 


Writing Data to a File 
Figure 10-1 shows an example of a simple text editor. It only writes new text to a 
file. Look closely at how the LINEOUTO function is used. 


/* World's smallest editor */ 
say "Type file name" 
pull filename 
say "Type as many lines as you like.", 
"To finish, press the Enter key only." 
do forever 
parse pull line 


if line = "" then /* empty line? os 
do 
call lineout filename /* if so, close the file */ 
exit /* and end the program */ 
end 


/* otherwise, write LINE to the end of the file */ 
call lineout filename, line 
if result = 1 then leave 

end 

say “Error, return code" result 

exit 


Figure 10-1. EDDY.CMD 
The user types a file name, which is then parsed by the PULL instructions and 
stored in the variable filename. As each line is typed: 

¢ The PARSE PULL instruction stores it as a string in the variable line. 


¢ The LINEOUTO( function (called as a subroutine) writes the string contained in 
line to the file name stored in the variable filename. 


¢ The DO loop continues until the user presses the Enter key twice, thereby 
entering a null string. 


¢ The program then calis LINEOUTO with only the filename (closing the file), 
and then exits. 
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Reading Data from a File 


LINEIN() Function 


LINES() Function 


To read the file and display the data on the screen, you could use the OS/2 
command TYPE. Use a REXX program to add some extra features. 


To read a line from a stream into a REXX program, use the LINEIN( function. 
For example: 


linein(stream) 
where: 


stream is name of the data stream (such as a file) from which the line is read. 


The first time LINEIN( is called in a program, it opens the named stream and 
returns the first line of data. The second time it is called, it reads the second line 
and returns the second line of data, and so on until the program ends (or you close 
the stream with LINEOUT(). In other words, LINEINO keeps track of its place in 
the stream with a kind of bookmark, called the read position. LINEOUT( uses a 
similar marker, called the write position. For more information, see “Accessing Data 
within a Stream” on page 10-20. 


LINEINO has no way of knowing when there are no more lines to read in a stream, 
such as when it gets to the end of a text file. To know when the read position has 
reached the end of the file, use the LINESQ function. 


To find out if any lines remain between the read position and the end of a stream, 
the function, lines(stream), returns: 


¢) if no complete lines remain to be read 


1 if any lines remain. 
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Figure 10-2 shows an example, where stream is a text file , so LINES() would return 
@ when the end of the file has been reached. 


/* Program to display an entire file */ 
/* exits when end-of-file is reached */ 


say "Type a file name" /* get the name of the file 
pull filename /* from the user 


lineno = 1 /* initialize a counter to display 
/* the line number 


do until lines(filename) = 0 /* repeat this loop until no lines 
remain in the selected file... 


say lineno linein(filename) display the line number, and then 
read and display a line of text, 
advancing the read position 
with each pass though the loop 


lineno = lineno + 1 increment the line-number counter 


end 
exit end the program 


Figure 10-2. SHOLIN1.CMD 


Resetting the Read Position 
Have the user select how many lines are displayed. If a number larger then the 
number of lines in the file is typed, the program cycles back to the beginning. To do 
this, use LINEINO with its second and third arguments. For example: 


linein(stream, position, count) 

where: 

stream is the name of the stream from which the line is read. 
position is the new position for the read position. The options are: 


¢ no argument (the default)—to leave the read position where it is. 
¢ 1—to set the read position to the beginning of the stream (line 1). 


count is whether or not to actually read a line. The options are: 
e 1 (the default)to read one line and advance the read position. 


¢ @Q to read no lines and not advance the read position. 


So far, LINEIN( has been used with the default values for the second and third 
arguments to simply read the next line. By setting 1 for the position and 0 for the 
count, LINEIN( can be used to reset the read position to the beginning of the 
stream without reading a line (or advancing the read position). For example: 


linein(filename,1,0) 


Since you are not interested in the return value (which would be empty anyway), you 
can call LINEINO as a subroutine: 


call linein filename,1,0 
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Figure 10-3 shows an example calling LINEINO as a subroutine to reset the read 
position. 


/* Displays a given number of lines in a text file 
/* If the given number exceeds the number of lines 
/* in the file then the read position is reset back 
/* to the beginning of the file 


say "Type a file name" 
pull filename 


say "Type number of lines to display" 
pull howmany 


lineno = 1 

do howmany 
say lineno linein(filename) 
lineno = lineno + 1 


if lines(filename) = 0 then /* if the end of file is reached */ 
do 
call linein filename,1,6 /* reset the read position 
say ">>> End of File <<<" /* display end-of-file marker 
lineno = 1 /* reset line counter 
end 


Figure 10-3. SHOLIN2.CMD 


Printing a Text File 
Using REXX to send data to a printer is very similar to writing to a file. There are 
some things you need to know: 


e The name of the device that your computer is connected. Use this device name 
in place of a file name. In Figure 10-4 on page 10-9, the printer device is 
named PRN. 


e The control characters and escape sequences that your printer uses for various 
formatting operations. Generally, these are listed in the manual for the printer. 
The example uses the standard character for a form feed, which directs the 
printer to start a new page. 


Sending Special Characters 
Printers often use certain characters as controls, such as ESC (escape) and FF (form 
feed) that you cannot type from the keyboard. To use these characters, you need to 
look up the ASCII number of the character. Then, you can use the built-in REXX 
function D2C( (decimal-to-character) to translate the ASCII code number into the 
character you need. 
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For example, the character that tells the printer to start a new page is ASCII number 
12. To translate that code number 12 into a character for the printer use, you would 
write, d2c(12). 


For more information about functions such as D2C(, see “Using Functions to 
Convert Data” on page 4-20. 


CHAROUT() Function 


A Printout Program 


Generally, the CHAROUTO function is most useful for issuing printer controls. 
CHAROUT (stream, string) 
where: 


stream is the name of the stream to which the character is written. Figure 10-4 
on page 10-9 shows an example where stream is the name of the device 
connected to a printer. 


string is a string—the characters to be written. 


Like the LINEOUT function, CHAROUTO returns 0 if all the characters in string 
are successfully written to stream. Unlike LINEOUTO, if for any reason 
CHAROUTDO cannot write to the named stream, it returns the number of characters 
that remain unwritten. 


CHAROUTO(O is also similar to LINEOUT(O in that it is more convenient to call it as 


a subroutine. For example, to tell the printer to start a new page, you could use 
call charout "PRN",d2c(12). 


Figure 10-4 on page 10-9 shows an example of a program for printing a file. 
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/* Prints a text file */ 
say ‘Type file name: ' /* prompt for a file name 
pull filename /* ...and get it from the user 


printer = 'PRN:' /* save name of printer device 
newpage = d2c(12) /* save page-eject character 


Repeat this loop until no lines remain in the file */ 
and keep track of the line count with COUNT */. 


count = 1 until lines(filename) = 0 

Read a line from the file ... */ 

output = linein(filename) 
. and send it to the printer */ 

call lineout printer, output 

if result <> 0 then /* if there isa */ 
do /* write error, */ 

say ‘Error: unable to write to printer' /* display it, and*/ 


leave /* exit the loop */ 
end 


if count // 50 = 0 then /* if the line count is a */ 

call charout printer, newpage /* multiple of 50, then */ 
/* start a new page by 

/* sending the form feed */ 


end go back to the start of loop 
until no lines remain 


call lineout filename close the file 
exit end the program normally 


Figure 10-4. PRINTIT.CMD 
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To Summarize 


Here is a review the input and output functions that have been used so far. 


Use this function To do this 


LINEOUT (stream, ] inedata) To open stream and append linedata 
(write it to the end of stream). Returns 
1 if successful; 0 if otherwise. 


LINEOUT (stream) To close stream when writing is 
completed. Returns 1 if successful; 0 if 
otherwise. (REXX automatically closes 
any open streams at the end of a 


program.) 
LINEIN(stream) or To open stream, read the first line and 
LINEIN(stream, ,1) advance the read position to the second 
line. 


If stream is already open, then 
LINEINO reads the current line and 
advances the read position one line 
ahead. 


LINEIN(stream, 1,0) To put the write position at the 
beginning of the stream without reading 
a line or advancing the read position. 


Although not discussed in this chapter, you can also: 


Use this function To do this 


LINEIN(stream,1,1) To put the write position at the 
beginning of the stream and specifically 
read the first line (advancing the read 
position to the second line). The action 
is the same whether or not stream is 
already open. 


LINEIN(stream, ,0) To open stream without reading the first 
line or advancing the read position. No 
action is taken if stream is already open. 


Figure 10-5 is a table showing the REXX functions that read from and write to a 
data stream. 


CHARIN() CHAROUT() CHARS() 
LINEIN( LINEOUT() LINES() 


Figure 10-5. Read and Write Functions 
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STREAM() Function 


Queues 


Lists of Data 


You can use the STREAM( function to get the following information about a 
stream: 


¢ To determine if a stream exists 
¢ To determine if a stream is ready for input or output 
© To get the size or last edit date of a file. 


You can also use STREAMO(O for more complex input and output tasks, as when 
your program must read from or write to: 


e Files other than text files 
e Streams other than files and printers 
e A specific position in a stream. 


See “STREAMO Function” on page 10-18 for examples of STREAM(. 


A queue is a means of holding a list of lines in a specific order. 


A queue in REXX combines the functions of a stack (in which the last item added is 
the first read) and a queue (in which the first item added is the first read). That is, it 
can be either /ast in, first out (LIFO) or first in, first out (FIFO). 


The REXX concept of a queue is different from that generally used. Throughout 
this book, the REXX definition a of queue is used. 


One particular advantage of using a queue is that it lets your REXX programs share 
data with other programs when those programs are written in REXX or any other 
language. 


Data in a queue is held as a series of lines. Thus, data can only be put on or taken 
off a queue one line at a time. A line of data can be added to the back or to the 
front of a queue, but a line of data can only be taken off from the front. 


The queue is external to REXX. Unlike variables, a queue remains even after your 
REXX program ends. Once created, it is retained for the duration of the current 
OS/2 session or until you delete it. This means that other programs can add or 
remove data from the queue whenever your REXX program allows. 


The difference between LIFO and FIFO is significant. Think of a queue as a list 
that you can add to from either end. You can add items on the back of the queue 
using the QUEUE instruction, or you can add items on the front of the queue, using 
the PUSH instruction. 
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You could picture it like this: 


back front 


QUEUE—> 
+—PUSH 


The concept of a queue having a front and a back is important, because you can 
only read items from the front of the queue. The command that reads data from a 
queue is the PULL instruction. 


Now you could picture it like this: 


back front 
<+——PUSH 
QUEUE——> 
——> PULL 


Putting Data on a Queue 
The QUEUE instruction puts an item of data on the queue in FIFO order: 


The PUSH instruction puts an item of data on the queue in LIFO order: 


back front 
1 {2 43 7 |+——PUSH 
+next item 
to be read 
first ite last ite 
added added 
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Reading the Queue 
Up to now, the PULL instruction has been used to collect user input, such as data 
typed at the keyboard, to store it into variables. 


What the PULL instruction actually parses is the next available line of data from the 
queue. It is only when the queue is empty (as it has been so far) that PULL parses 
input from the keyboard. 


Try the program shown in Figure 10-6. 
/* Using QUEUE and PULL */ 


QUEUE time() /* add the current time to the queue 
QUEUE date() add the current date to the queue 


PULL datal /* get a string from the queue front 


PULL data2 /* get a string from the queue front 


say ‘The first element on the queue was:' datal 
say 'The second element on the queue was:' data2 


exit /* end the program normally 


Figure 10-6. QUEUING.CMD 


Change the program by substituting PUSH for QUEUE, see Figure 10-7. 


/* Using PUSH and PULL */ 
push time() /* add the current time to the queue 
push date() /* add the current date to the queue 


pull Datal /* get a string from the queue front 
pull Data2 /* get a string from the queue front 


say 'The first element on the queue was:' Datal 
say 'The second element on the queue was:' Data2 


exit /* end the program normally 


Figure 10-7. PUSHING.CMD 


QUEUED Function 
It would be useful to be able to determine how many items are on the queue at any 
given time. That is the purpose of the REXX function QUEUED, see Figure 10-8. 


/* counting the queue */ 
push "manny" 
push "moe" 


push "mac" 
count = queued() 
say count "names in queue." /* displays ‘3 names in queue. ' af 


Figure 10-8. QCOUNT.CMD 
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You will find that QUEUED is particularly useful for controlling a DO loop that 
pulls data from the queue, see Figure 10-9. 


/* Find al] DEVICE= lines in C:\CONFIG.SYS, put them in */ 
/* the queue, and process them later */ 
file = "C:\CONFIG.SYS" 

Do While Lines(file) > 0 

line = Linein(file) 

If Translate(Left(line,7)) = 'DEVICE=' Then Push line 

End 


Say ‘There are' queued() 'DEVICE= lines in' file'. Here they are 
Do queued() 

Parse Pull line 

Say line 

End 


Figure 10-9. DOQUEUE.CMD 


Summary 
This completes “Basics” in this chapter. You have learned how to: 


¢ Read and write disk files 
e Send data to the printer 
e¢ Use the REXX data queue. 


To make best use of the topics discussed in this chapter, see “Data Streams” in the 
REXX Reference. 


“Advanced Topics” in this chapter discusses more about input and output. 


To continue with “Basics,” go to page 11-1. 
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rn 


Advanced Topics 


In this chapter: 
Advanced Topics 


More about data streams 
Default streams 

STREAMO function 
Accessing data within a stream 
More about queues. 


> 
> 
> 
> 
> 


More about Data Streams 


Default Streams 


REXX regards all information from any file or device as a continuous stream of 
single characters. Data read into a REXX program (whether from a disk file, the 
keyboard, a device, or another program) is processed equally as a character stream. 
The same is true for output data that a REXX program writes to a file or other 
device. All of these are streams. 


Your program can work with the information in a stream as it is, | character at a 
time. Or, if the data is in line form (as in a text file), you can manipulate the 
information from the stream (or put information into it) line-by-line. 


As shown in “Basics” in this chapter, your REXX programs can access and 
manipulate text files by using: 


LINEINO to read a line 

LINEOUTO to write a line 

LINESO to check for the end of the stream 

CHARINO to read 1 or more characters 

CHAROUTQ to write 1 or more characters 

CHARSQ to count the characters remaining in the stream. 


Each of the I/O functions listed here has as its first argument the name of a stream 
that is read or written to. Each of these functions also has a default stream that is 
used if you omit the name of a specific stream. STDIN is the default input stream 
(for LINEIN( and CHARIN( functions). STDIN is any data that is typed at the 
keyboard. 


This means that you can use the LINEIN() function to pause processing and read a 
line typed at the keyboard, as you can with the PARSE PULL instruction. But note 
these differences: 


° Unlike PARSE PULL, the LINEINO function reads only keyboard entries, 
regardless of whether there are outstanding items on the default data queue. 


e LINEINO does not prompt the user with a question mark. 
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To understand how this works, use the first file-reading program, SHOLIN1I.CMD 
(see Figure 10-2 on page 10-6) and add an instruction as shown in Figure 10-10. 


/* Displays a file one line at a time 

/* as the user presses the Enter key; program 
/* ends when the end-of-file is reached 

/* OR if user types any character. 


say "Type a file name" 
pull filename 
lineno= 1 


do until lines(filename) = 0 
say lineno linein(filename) 
if linein() \= "" then leave /* waits for user to press the Enter*/ 
/* key; if anything else is typed */ 
/* (if LINEIN() does not return */ 
/* an empty string), then the */ 
/* loop (and the program) ends */ 
lineno = lineno + 1 
end 
exit 


Figure 10-10. SHOLIN3.CMD 
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Or, you could modify the cycling version of this program, SHOLIN2.CMD (see 
Figure 10-3 on page 10-7) to let the user choose the number of lines to display. To 
do this, put the display routine inside a DO FOREVER loop, as shown in 

Figure 10-11. 


/* Displays a file one line at a time */ 
as the user presses the Enter key, or*/ 
displays a given number of lines. 
Cycles back to the beginning of the 
file when the end-of-file is reached 
Program ends only when user types 
any non-numeric character. 


say "Type a file name" 
pull filename 


say "Type a number of lines to display” 

say “or press the Enter key alone to advance one line" 
say "Type any other character to end." 

lineno = 1 


do forever 
howmany = linein() /* pause for user entry and store */ 
/* it in the variable HOWMANY a} 


if howmany = “" then howmany = 1 /* pressing the Enter key alone 
/* is the same as typing '1' 


if \datatype(howmany,n) then leave/* typing any non-numeric 
/* character ends the program 


do howmany 
say lineno linein(filename) 
lineno = lineno + 1 


if lines(filename) = 0 then 
do 
call linein filename,1,0 
say ">>> End of File <<<" 
lineno = 1 
end 


Figure 10-11. SHOLIN4.CMD 


Parsing Default Input 
You can parse the input for individual words, either by using the instruction: 


PARSE VALUE linein() WITH varl var2 ... 
or with the shorter form built into the PARSE instruction: 
} PARSE LINEIN varl var2 ... 
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For more information about the PARSE instruction and its options, see Chapter 8, 
“Parsing.” Also, see “Parsing” in the REXX Reference. 


STREAM() Function 
For more intricate and specialized input and output tasks, REXX provides another 
function called STREAM(. For example: 


STREAM(name, operation, command) 


where: 
name is the stream you want to work on 
operation is one of these: 
C for a command or action to be taken 
S for the state of the stream 
D for a more detailed description. 
command is an action to perform. This argument must be used when and 


only when you specify C as the operation. 
The syntax may look a bit complicated at first, because STREAM(O has a wide 
variety of applications such as: 


¢ The C (Command) operation lets your program select and gain access to a named 
stream. 


¢ The operations S and D (state and description) report the current status of a 
stream; that is, whether: 


— the stream is READY or NOTREADY for input/output 
— itis UNKNOWN (not yet identified) 
— an input or output ERROR has occurred. 


For the full syntax of STREAMO and the other REXX input and output functions, 
see the REXX Reference. 


Getting Information about a Stream 


To determine if a particular stream exists, use the stream command QUERY EXIST 
with the STREAMO function call. For example: 


stream(name,C,'query exists') 
Note that the stream command is enclosed in matching quotes. 


If the stream name exists, then this function call returns the full-path specification of 
the stream. For example: 


C:\WORK\MYFILE. TXT 


If the stream name does not exist, then the result is a null string. 
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Figure 10-12 shows an example of a program that reads a file. 


/* For a program that reads a file */ 

say "Type a file name (or press the Enter key alone to exit): " 
pull fname 

if fname = "" then exit 


/* Check that the file exists: 

if STREAM() returns a null string, 
/* then report the stream not found 
/* and exit.... 


call stream fname, C, ‘query exists' 
if result = "" then 
do 
say "Can not find" fname"." 
say "Check for proper path specification." 
exit 
end 


/* ...else store the full pathname */ 
/* (in RESULT) to the variable FNAME, */ 
/* in case the user has typed a * 
/* relative path (e.g., "..\docs\my.txt" */ 


else fname = result 
say "Full path specification is" fname 


Figure 10-12. QRYFILE1.CMD 


You can also query for information about the size of a stream and the date and time 
of the last edit, see Figure 10-13. 


/* How big and when last changed? */ 
say "Type a file name (or press the Enter key alone to exit): " 
pull fname 


bytes = stream(fname,c,'query size') 
ledit = stream(fname,c,'query datetime') 
say fname "is" bytes "bytes." 

say "Last edit of" fname "was" ledit"." 


Figure 10-13. QRYFILE2.CMD 


Opening and Closing Streams 
The functions LINEOUTOQ, LINEINOQ, CHARINO and CHAROUT( do much of 
their own housekeeping. They automatically open the streams they work on and 
leave REXX to close the stream at the end of a program. 


However, there are cases where it is necessary (or at least more prudent) to explicitly 


open and close a stream, such as in a program that reads from more than one device 
or one that writes to the middle of a file. 
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This is done with the STREAMO function: 
stream(name,c,“open") 
This default form opens a stream name for both reading and writing text. To open a 
stream for: 
e Writing only, add the word write. For example: 
stream(name,c,"open write") 
e Reading only, add the word read. For example: 


stream(name,c,“open read") 


When you open a stream in this way, STREAM(O returns the string READY: if the 
stream has been successfully opened. An error message is returned if for any reason 
it was unable to open the stream. 


To explicitly close a stream, use: 


stream(name,c,"close") 


In this form, STREAMO returns the string READY if the operation is successful, the 
string ERROR if the operation fails. 


Accessing Data within a Stream 
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REXX regards all external data as streams of information. Nonetheless, these 
streams can take different forms. A disk file, for example, differs from the output to 
a printer in that it has a static, physical form. A disk file is one example of a 
persistent stream. This means a disk file can not only be read from its beginning or 
written to its end, it can be read from and written to any place between. 


As a program reads a file, REXX keeps a place marker, called the read position, that 
points to the next character (or line) to be read. 


The same is true when writing. REXX maintains a write position that marks the 
next place it is to write. 


When both reading and writing a file, the read position and the write position are 
the same. The read position and the write position are always the same. When one 
moves, the other also moves. 


If you do not specify a position for these markers, REXX advances them, by default, 
the number of characters read or written. 


You can specify another position for the read or write positions by giving additional 
arguments to the stream functions, LINEINO, LINEOUTQ, CHARINO, 
CHAROUTO, or by using the position option of the STREAMO function. For 
more information, refer to “Functions” in the REXX Reference. 
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More about Queues 


Examples 


In certain applications, your REXX programs can organize information for use by 
other programs by putting it in an external data queue. A queue is an ordered list 
that can be read or written at either end, top or bottom, so that each item of the 
queue constitutes a line of data. 


There are two kinds of queues in REXX: 


¢ One default queue, SESSION, is automatically provided for each active OS/2 
session. SESSION is created by REXX the first time a REXX program issues a 
PUSH or QUEUE instruction to a line of data. Any program, REXX or 
otherwise, in a given session can access the SESSION queue, but only the 
SESSION queue defined for its own session can be accessed. 


e A REXX program can also create private queues for itself. A private queue 
must be accessed by a unique name. You can name the queue or leave the 
naming to REXX. 


Private data queues are created and manipulated by the RXQUEUE function, 
described in “Applications Programming Interfaces” in the REXX Reference. 


For more information about file and device input and output, refer to “Functions” 
and “Data Streams” in the REXX Reference. 


/* SDIR.CMD - Program to print a sorted directory. 
/* Program will read in the current directory, and 
/* then sort it using a quick-sort routine. 
list. = 0 
'dir | rxqueue /fifo' 
j=0 
do queued() 

j=jtl 

parse pull list.j 

end 
call quicksort 4, j-l 
do i = 1 to j 

say list.i 
end 
exit 0 
/* The quick-sort procedure */ 
Quicksort: 
PROCEDURE EXPOSE list. 
ARG bot, top 
center = Qsort(bot, top) 
IF center - 1 > bot THEN CALL Quicksort bot, center - 1 
IF center + 1 < top THEN CALL Quicksort center + 1, top 
RETURN 


Figure 10-14 (Part 1 of 2). SDIR.CMD 
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qsort: PROCEDURE EXPOSE list. 
ARG b , t 
choose = list.b 
small = b 
large =t+1 
DO WHILE (small + 1 < large) 
next = small + 1 
IF list.next <= choose THEN 
DO 
list.smal] = list.next 
small = small + 1 
list.next = choose 


large = large - 1 
temp = list.Jarge 
list. large = list.next 
list.next = temp 
END 
END 
RETURN small 


Figure 10-14 (Part 2 of 2). SDIR.CMD 


/* Program printing exec - program will determine which records af 
/* ina file exceed the specified length. */ 


say ‘Please type the name of the file to examine {filename.ext}: ' 
parse pull file 
say 'Please type the length to scan for: ' 
parse pull col 
"type" file "| rxqueue /fifo" 
if rc <> @ then exit rc 
lines = queued() 
do currline = 1 to lines 
parse pull line 
if length(line) > col then 
say ‘Line #' currline ' length =' length(line) 
end 
exit 0 


Figure 10-15. LINLEN.CMD 
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Basics 


Chapter 11. Program Style 


The focus in this chapter is more on method than on individual features, which are 
better learned by practicing and experimenting. 


In this chapter: 


Basics 


Consider the data 
Define the tasks 
Create modules 


Planning the program 
Putting it all together 
Testing and debugging. 


As you learn more about the syntax of REXX, you can get better at deciding which 
computing tasks are appropriate to a program. Translating an idea for a program 
into actual code is less a matter of expert programming than of good planning. If 
you plan your program thoroughly, the coding will be that much easier. 


Consider the Data 
When you are faced with the task of writing a program, the first thing to consider is 
the data you are required to process. 


Test Yourself 


i; 


Make a list of the input data. What are the items and the possible values of 
each? 


. If the input data items have a type of structure or pattern, draw a diagram to 


illustrate it. 


. Do the same for the output data. What data and in what form does the user 


expect as output? 


. Study your two diagrams to see if they fit together. If they do, you are well on 


the way to designing your program. 


. Write a specification of input for the user. This may be a written specification, a 


HELP file, or both. 


You are required to write an interactive program that invites the user to play heads 
or tails. The game can be played as long as the user likes. To end the game, the 
user types Quit in answer to the question Heads or Tails?. The program is arranged 
so that the computer always wins. 


Think about how you would write this program. 
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The computer starts with: 


Let us play a game! Type "Heads", "Tails", or "Quit" 
and press the Enter key. 


This means that there are four possible inputs: 


Heads 

Tails 

Quit 

None of these three. 


And so the corresponding outputs should be: 


e Sorry. It was TAILS. Hard luck! 

e Sorry. It was HEADS. Hard luck! 

¢ (no output) 

¢ That is not a valid answer. Try again! 


This sequence must be repeated indefinitely, ending with the return to the OS/2 
program. 


Now that you understand the specification, the input data, and the output data, you 
are ready to write the program. 


Write the program. If you are careful, it should run the first time. 


Answer: Figure 11-1 is an example of a possible solution. 


/* Tossing a coin. The machine is lucky, not the user */ 


do forever 
say "Let us play a game! Type 'Heads', 'Tails'", 
"or 'Quit' and press the Enter key." 
pull answer 


select 
when answer = "HEADS" 
then say "Sorry! It was TAILS. Hard luck!" 
when answer = "TAILS" 
then say "Sorry! It was HEADS. Hard luck!" 
when answer = "QUIT" 
then exit 
otherwise 
say "That is not a valid answer. Try again!" 
end 
say 
end 


Figure 11-1. CON.CMD 
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Define the Tasks 


You are going to knit a warm, woolen, pullover sweater to wear when you go 
sailing. You may: 


. Knit the front 

. Knit the back 

. Knit the left arm 

. Knit the right arm 

. Sew the pieces together. 


OA B&B WN — 


Each of these jobs is simpler to describe than the the job of knitting. In computer 
jargon, separating a job into simpler jobs is called stepwise refinement. 


Look at the specification again. You may need to put on the pullover in the dark 
quickly, without worrying about the front or back. Therefore, the front should be 
the same as the back, and the two sleeves should also be the same. Figure 11-2 
shows a way that this could be coded. 


do 2 
CALL Knit_body_pane] 
end 


do 2 


CALL Knit_sleeve 
end 


CALL sew_pieces_together 


Figure 11-2. PULLOVER.CMD 


Reconsider the Data 


When you are refining your program, your objective is to make each piece simpler. 
This means simpler: 


Input data for each segment or routine 
Output data for each segment or routine 
Processing 

Code. 


In the preceding example, if your pieces really are simpler, they probably have 
simpler names, too. For example: 


e Knit cuff. 
rather than 


e Make ribbing for cuffs and waistband. 
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Create Modules 
Using the stepwise refinement method discussed previously, you start with a 
specification (which may be incomplete). Then, you separate the proposed program 
into routines, so that each routine is easier to code than the entire program. You 
repeat the process for each of these routines until you reach routines that you are 
sure you can code correctly the first time. 


While you are doing this, keep asking yourself two questions: 
¢ What data does this routine handle? 
e Is the specification complete? 
Still thinking about method, which is as important as language, look at a simple 


_arcade-type game program called CATMOUSE.CMD, as shown in Figure 11-3. 
You may want to take a moment to type it in and play it. 


/* The user says where the mouse is to go. But where 
/* will the cat jump? 


say "This is the mouse 

say "These are the cat's paws ---> ( )" 

say "This is the mousehole 

say "This is a wall 

say 

say "You are the mouse. You win if you reach", 
"the mousehole. You cannot go past" 

say "the cat. Wait for him to jump over you.", 
"If you bump into him you are caught!" 

say 

say "The cat always jumps towards you, but he's not", 
"very good at judging distances." 

say "If either player hits the wall he misses a turn" 

‘Say 

say "Type a number between 0 and 2 to say how far to", 
"the right you want to run.“ 

say "Be careful, if you type a number greater than 2 then", 
"the mouse will freeze and the cat will move!" 

say 


Figure 11-3 (Part 1 of 3). CATMOUSE.CMD 
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length of corridor 

position of hole 

maximum distance cat can jump 
mouse starts on left 

cat starts on right 


pull move 
if datatype(move,whole) & move >= 0 & move <= 2 
then select 
when mouse + move > len then nop /* hits wall 
when cat > mouse, 
& mouse + move >= cat /* hits cat 
/* continued ... 
then mouse = cat 
otherwise /* moves 
mouse = mouse + move 
end 
if mouse = hole then leave /* reaches hole 
if mouse = cat then leave /* hits cat 


jump = random(1,spring) 

if cat > mouse then do /* cat tries to jump left 
if cat - jump < 1 then nop /* hits wall 
else cat = cat - jump 

end 

else do /* cat tries to jump right 
if cat + jump > len then nop /* hits wall 
else cat = cat + jump 

end 

if cat = mouse then leave 

end 


Figure 11-3 (Part 2 of 3). CATMOUSE.CMD 
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call display 
if cat = mouse then say "Cat wins" 
else say "Mouse wins" 


/* Subroutine to display the state of play 
f/* 
Input: CAT and MOUSE 


Design note: each position in the corridor occupies 
three character positions on the screen. 


display: 
corridor = copies(" ",3*len) /* corridor 
corridor = overlay("0",corridor,3*hole-1) /* hole 


if mouse \= len /* mouse in hole? */ 
then corridor = overlay("@",corridor,3*mouse-1)/* mouse */ 


corridor = overlay("(",corridor,3*cat-2) /* cat */ 
corridor = overlay(")",corridor,3*cat) 

say " |"corridor"!" 

return 


Figure 11-3 (Part 3 of 3). CATMOUSE.CMD 
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Planning the Program 
The program is about a cat and a mouse and their positions in a corridor. 


1. The program begins with some initial settings, such as the length of the corridor 
and the positions of the cat and the mouse. 


2. The player types the moves of the mouse. The cat’s jumps are generated using a 
random number. The resulting positions are calculated at some point. 


3. At some other point, these positions are displayed on the screen. 


Obviously, the whole program is too complicated to think about all at once. The 
first step is to separate it into tasks such as: 


e¢ Setup—establish the initial positions. 
e Main program—accept and calculate the result of each move. 


¢ Display subroutine—display the new positions. 


Now look at the main program. The user (who plays the mouse) will want to see 
where everybody is before making a move. The cat will not. The next step is to 
separate the main program into: 


Do forever 
call Display 
Mouse's move 
Cat's move 

End 

Conclusion 


Designing Loops 
The method for designing loops is to ask two questions: 


e¢ Will it always terminate? 
e Whenever it terminates, will the data meet the conditions required? 


The loop terminates (and the game ends) when: 


¢ The mouse runs to the hole. 
e The mouse runs into the cat. 
e The cat catches the mouse. 


Conclusion 
At the end of the program, the user must be told what happened by issuing the 
following: 


call display 
say who won 
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Putting It All Together 


Figure 11-4 shows how to put the modules together: 


if mouse = hole then leave /* reaches hole 
if mouse = cat then leave /* hits cat 


call display 
if cat = mouse then say "Cat wins" 
else say "Mouse wins" 


/* Subroutine to display the state of play 
/* Input: CAT and MOUSE 


display: 


Figure 11-4. CATMOUSE2.CMD 


Testing and Debugging 


If you cannot understand why your program is giving wrong results, you can: 
¢ Modify your program so that it tells you what it is doing 


e Put extra instructions into your program, such as: 


say "Checkpoint A. x =" x 


say "End of first routine" 


e Use some of the REXX interactive trace facilities. 


You will gradually learn which of these techniques is best for you. 
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Using TRACE 
The TRACE instruction is a facility that you can use to perform the following tasks. 


¢ To find out where your program is going, use TRACE L (labels). Figure 11-5 
shows an example and the trace it displays on the screen. 


/* Example: two iterations of wheel, six iterations */ 
/* of cog. On the first three iterations, "x < 2" */ 
/* is true. On the next three, it is false. */ 
trace L 
do x = 1 to 2 
wheel: 

do 3 
cog: 


if x < 2 then do 


true: 
end 
else do 

false: 
end 

end 
end 
done: 


Figure 11-5. ROTATE.CMD 


The following trace is displayed on the screen. 


[C:\]rotate 
6 *-* wheel: 
8 *-* cog: 
10 *-* true: 
8 *-* cog: 
19. :*-* true: 
8 *-* cog: 

10 *-* true: 
*-* wheel: 
*-* cog: 

*.* false: 
*.* COG: 

*.* false: 
*-* COG: 

*.* false: 
*-* done: 


® To see how the interpreter is computing expressions, use TRACE I 
(intermediates). 


© To find out whether you are passing the right data to a command or subroutine, 
use TRACE R (results). 


¢ To make sure that you get to see nonzero return codes from commands, use 
TRACE E errors). 
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TRACE Symbols 


The trace symbols mean: 


ta* Identifies the source of a single clause, that is, the data actually in the 
program. 


+++ Identifies a trace message. This may be the nonzero return code from a 
command, the prompt message when interactive debug is entered, an 
indication of a syntax error when in interactive debug, or the traceback 
clauses after a syntax error in the program. 


>>> Identifies the result of an expression (for TRACE R), the value assigned to a 
variable during parsing, or the value returned from a subroutine call. 


>.> Identifies the value assigned to a placeholder during parsing (see “Using a 
Placeholder” on page 8-7). 
If you are using TRACE I (intermediates), these symbols are also used: 


>C> The data traced is the name of a compound variable, traced after 
substitution and before use, provided that the name had the value of a 
variable substituted into it. 


>F> The data traced is the result of a function call. 


>L> The data traced is a literal (string, uninitialized variable, or constant 
symbol). 


>0> The data traced is the result of an operation on two terms. 
>P> The data traced is the result of a prefix operation. 


>V> The data traced is the contents of a variable. 


Interactive Debugging 


Summary 


By putting a question mark in front of the TRACE option, TRACE ?R, you can turn 
on the REXX interactive debugging tool. That means the program pauses after it 
processes most instructions (exceptions include SIGNAL, CALL, and reiterations of 
DO loops). You can examine each clause, one at a time, and advance processing by 
pressing the Enter key. 


For more information about interactive debug, refer to “Debug Aids” in the REXX 
Reference. 


This completes “Basics” in this chapter. You have learned how to: 


¢ Define tasks and create program modules 
¢ Plan and develop a program 
e¢ Test and debug a program. 


“Advanced Topics” in this chapter discusses refining programs to make them easier 
to read. 


11-10 REXX User’s Guide 


Advanced Topics 
In this chapter: 


Advanced Topics 


>» Making programs easy to read. 


Making Programs Easy to Read 
The only sure way to determine if a program is correct is to read it. Therefore, 
programs must be easy-to-read. Easy to read means different things to different 
programmers. Here are examples of different styles. You can choose the style you 
prefer. 


A very good way to check your program is to ask someone to read it. Be sure to 
choose a coding style that they find easy to read. 


Most people would find the program fragment shown in Figure 11-6 difficult to 
read. 


KIKI IIIA IIHR IRR ERI IISA III IIIA IAI I IAI AI III IIIA III AAAI 


/* SAMPLE #1: A portion of CATMOUSE.CMD (Page 11-4), */ 
/* not divided into segments and written with no indentation */ 
/* and no comments. This style is not recommended. +]. 
[REALL EAA LIENS SEE I SATA ETRE RENE INT SI OST LEINT ERE EE | 
do forever 

call display 

pull move 

if datatype(move,whole) & move >= 0 & move <=2 

then select 

when mouse+move > len then nop 

when cat > mouse, 

& mousetmove >= cat, 

then mouse = cat 

otherwise 

mouse = mouse + move 

end 


if mouse = hole then leave 


if mouse = cat then leave 
jump = random(1,spring) 

if cat > mouse then do 

if cat-jump < 1 then nop 
else cat = cat-jump 

end 

else do 

if cat+jump > len then nop 
else cat = cat+jump 

end 

if cat = mouse then leave 
end 

call display 

if cat = mouse then say "Cat wins" 
else say "Mouse wins" 

exit 


Figure 11-6. CATMOUSE3.CMD 
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Figure 11-7 shows an example that is easier to read. It is separated into segments, 
each with its own heading. The comments on the right are sometimes called 
remarks. They can help the reader get a general idea of what the program is doing. 


[ESPEREEESRERERSEREERE NEE ES EER ERSERERSRER ER ERENEEAER RAD | 


/* SAMPLE #2: A portion of CATMOUSE.CMD (Page 11-4), 
/* divided into segments and written with ‘some' 


/* indentation and ‘some' comments. */ 
[ECEFRESE REELS ES AE SEN AEASERAERERARALE SER ERAANEAEREBRE NERD / 


[BERAERAEESEERRTRERRERAESER NEARER EERARER REAR RR REEERERER EES | 


/* Main program: */ 
[RERRERNEERR AREER REET EAAEERARARA RAR ERARTED ARERR NARRERE | 
do forever 

call display 


[RESRESSEREEAEAASERHEEEEN NS CEERALEREREEENEREANARRES EER | 


/* Mouse's turn *). 
[ERE IIL IIASA LER IAID IRENE EAA] 
pull move 
if datatype(move,whole) & move >= 0 & move <=2 
then select 
when mouset+move > len then nop /* hits wall */ 
when cat > mouse, 
& mouse + move >= cat, /* hits cat */ 
then mouse = cat 
otherwise /* moves *) 
mouse = mouse + move 
end 
if mouse = hole then leave /* reaches hole */ 
if mouse = cat then leave /* hits cat *} 
JERE EN SE ELAR RENE EEN ENS RENAN REN ENT ESREL RMN SESE RE ES 


/* Cat's turn sd 
Y FAERSAEEEET ECR ESEAAS ENSSSENSRUN AS EONS VERON ESAS SAA EAS) 
jump = random(1,spring) 
if cat > mouse then do /* cat tries to jump left */ 
if cat - jump < 1 then nop /* hits wall */ 
else cat = cat - jump 
end 
else do /* cat tries to jump right */ 
if cat + jump > len then nop /* hits wall */ 
else cat = cat + jump 
end 
if cat = mouse then leave 
end 
[PO RLEESES ESE ER ESENSESARELRNAANAERAREEASEAEREE AER EERE ED / 


/* Conclusion */ 
[PEE ESTRELESSAES ER REALS ANAAEEERERES ER NAT SAREE SEAS LES A SED | 
call display 

if cat = mouse then say "Cat wins" 

‘else say "Mouse wins" 

exit 


Figure 11-7. CATMOUSE4.CMD 
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Figure 11-8 shows an example with additional features that are popular with some 
programmers. Keywords written in uppercase and a different indentation style 
highlight the structure of the code. The abundant comments recall the detail of the 
specification. 


HIKARI RARER ARIE ER ERERAER AIA AAAI RIKER 


/* SAMPLE #3: A portion of CATMOUSE.CMD (Page 11-4), 
/* divided into segments and written with ‘more’ 
/* indentation and 'more' comments. 


/* Note commands in uppercase (to highlight logic) */ 
[BEERRERERREREREER IRR AR ERAN A RETR ETRERETEER ERAT IAAIR TITRE | 


[BRRERRRIA RARER ERE RERE RII NER ARENT TAIRA RE LATEST IIA TELE | 


/* Main program */ 
FIR IRR ITI TIAA II IIIA ESI EIIAII A ITA I A I I II I I IT A IIE. 
DO FOREVER 
CALL display 


HHKKKREKEK RARER EKER ERE RI IRRER ERIE | 


/* Mouse's turn */ 
JEEEREREEREEEREEEEA ERAN RET ERERS EEE | 
PULL move 
IF datatype(move,whole) & move >= 0 & move <=2 
THEN SELECT 
WHEN mousetmove > len /* mouse hits wall */ 
THEN nop /* and loses turn */ 
WHEN cat > mouse, 
& mousetmove >= cat, /* mouse hits cat */ 
THEN mouse = cat /* and loses game */ 
OTHERWISE mouse = mouse + move /* mouse ... */ 
END /* moves to new location */ 
IF mouse = hole THEN LEAVE /* mouse is home safely */ 
IF mouse = cat THEN LEAVE /* mouse hits cat (ouch) */ 


HHAKKREKEERER IARI RIA RAAIIIAER | 


/* Cat's turn */ 
HIKKKKKEKEKEREREEKKEEREEEEEEREEEEEE 
jump = RANDOM(1,spring) /* determine cat's move */ 
IF cat > mouse /* cat must jump left */ 
THEN DO 
IF cat-jump < 1 /* cat hits wall +) 
THEN nop /* misses turn *} 
ELSE cat = cat-jump /* cat jumps left */ 
END 
DO /* cat must jump right */ 
IF cat+jump > len /* cat hits wall */ 
THEN nop /* misses turn ¥y 
ELSE cat = cat+jump /* cat jumps right */ 
END 
= mouse THEN LEAVE /* cat catches mouse */ 


/*continued*/ 


Figure 11-8 (Part 1 of 2). CATMOUSES.CMD 
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SPRANG R RANA NSE ON SOA SARREE TRESS SONS EERE RENAN EE AERS / 


/* Conclusion */ 
KEKEKKERKEEEEKEREEREREREREREREREREERERERREREEKERERREREREKREE 


CALL display /* on final display */ 
* 


IF cat = mouse who won? 
THEN say "Cat wins" /* ... the cat A 
ELSE say "Mouse wins” -.. the mouse */ 
EXIT 


Figure 11-8 (Part 2 of 2). CATMOUSES.CMD 
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NS 


Chapter 12. Using REXX with Applications 


The early chapters in this book familiarized you with the REXX language and 
showed you how to create and run REXX programs. This chapter builds on that 
knowledge with some REXX features designed to get the most out of your OS/2 
system. These features enable you to customize your system and write more 
powerful programs. 


Basics 
In this chapter: 


> Customizing OS/2 programs 
> Getting the most from OS/2 


> REXX utility functions. 


Customizing OS/2 Programs 
Your REXX programs can customize the way OS/2 programs work. If you always 
start an application with the same set of parameters, you can write a REXX 
program to call the application. This saves typing each time you use an application. 
You also do not need to remember the application parameters and options; REXX 
remembers them for you. 


Accessing Command Environments 
When you place the DIR command in a REXX program, REXX gives the command 
to the CMD.EXE program. CMD.EXE processes the command and gives a return 
code back to REXX. CMD.EXE is not the only program REXX can send 
commands. Any application can create a command environment for REXX 
programs to use. The application command environments create new sets of 
commands that you can use. | 


For example, the IBM Extended Services/2 product provides communications 
support command environment. To use the communications command environment, 
you must use the REXX ADDRESS instruction. The ADDRESS instruction tells 
REXX to send commands to the communications program instead of the 
CMD.EXE program. The communications environment is called CPICOMM. 
Figure 12-1 shows a REXX program that uses the CPICOMM command 
environment. 


/* Start of a program that uses SAA communications support */ 

Address CPICOMM 

destination = "SYSTEMA" /* prepare input for CMINIT command */ 
"CMINIT conv_id destination cm_rc" Issue CMINIT command to CPICOMM. 


The meaning of CMINIT and what 
its parameters are defined by 
the SAA communication program, 
not by REXX. 


Figure 12-1. CPICOMM 
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You must run the CPICREXX command before you can use the CPICOMM 
command environment. More commonly, you must use the RXSUBCOM command 
to create a command environment. The RXSUBCOM command tells REXX which 
program it should pass REXX program commands. For example, REXX Dialog 
Manager programs use RXSUBCOM to create the ISPCIR subcommand handler: 


"RXSUBCOM REGISTER ISPCIR ISPCIR ISPCIR' 
Address ispcir 


The Dialog Manager ISPCIR subcommand environment is a routine named ISPCIR 
in the ISPCIR.DLL dynamic link library. You must issue the instruction 
ADDRESS ISPCIR to send commands to the Dialog Manager. 


Using External Functions 


Summary 


In addition to the REXX built-in functions, you can use functions external to REXX 
in your REXX programs. An external function may be simply another REXX 
program, or it may be a function written in a compiled language. Before you can 
use a function in a compiled language, you must tell REXX where the function is 
located with the RxFuncAdd function. 


For example, the IBM Extended Services/2 product provides a REXX function for 
the Emulator High Level Language Application Programming Interface (EHLLAPI). 
The EHLLAPI function is in an OS/2 dynamic link library module named 
SAAHLAPI.DLL. The function routine within SAAHLAPI.DLL is HllApiSrv. To 
use the EHLLAPI function, you must first tell REXX where the function is found: 


call RxFuncAdd 'hilapi', 'saahlapi', ‘hllapisrv' 


You can now use the function HLLAPI in your REXX programs: 


hilapi("Set_session_parms", "CONPHYS") 
hl lapi("Connect", session) 
rc <> Q) then return rc 


rc 
rc 
if 
re = hilapi("Start_keystroke_intercept",session,"L") 


i-m i tt 


You only need to register HLLAPI with RxFuncAdd one time. Once registered, a 
function is available from anywhere on your OS/2 system. 


This completes “Basics” in this chapter. You know how to: 


e Start an application efficiently 
e Send commands to applications 
e Use external functions. 


“Advanced Topics” in this chapter discusses REXX utilities. 


Advanced Topics 


In this chapter: 
| > REXX Utility Functions : 
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The REXXUTIL external function package 
Rexx Util is a Dynamic Link Library (DLL) package of OS/2 operating system 
REXX functions. These operating system functions: 


¢ Manipulate OS/2 operating system files and directories 
¢ Manipulate OS/2 operating system classes and objects 
¢ Perform text screen input and output. 


To use a RexxUtil function, you must first register the function with the REXX 
RxFuncAdd function: 


Add RexxUtil Function 
call RxFuncAdd 'SysCls', 'RexxUtil', 'SysCls' | 


The RxFuncAdd function can register functions in other dynamic link libraries as 
well. 


The example above registers the SysCls function. You can now use the SysCls 
function in your REXX programs. 


The SysLoadFuncs RexxUtil function automatically loads the other RexxUtil 
functions. The following instructions in a REXX program will register all of the 
Rexx Util functions. 

Load RexxUtil Function 
call RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs' 


call SysLoadFuncs 


Once registered, the RexxUtil functions are available from all OS/2 operating system 
sessions. If you use the RexxUtil functions frequently, you should place a call to 
SysLoadFuncs in your STARTUP.CMD file. 


Functions that Replace Commands 
Several RexxUtil functions duplicate OS/2 operating system command functions. 
The command functions are: 


SysMkDir 
Creates a directory 


SysRmDir 
Deletes a directory 


SysFileDelete 
Deletes (erases) a file 


SysCls 

Clears the screen. 
The RexxUtil command functions have several advantages over the equivalent 
operating system commands: 


e The RexxUtil functions do not issue error messages. For example, for a file that 
does not exist, the DELETE command issues the message: 


SYSQ002: The system cannot find the file specified. 
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if you wish to unconditionally erase the file, you would need to redirect the error 
message: 


‘del’ file '>NUL' 


The RexxUtil SysFileDelete function can do this easily, without an error 
message: 


call SysFileDelete file 


¢ The RexxUtil functions calls are not echoed to the screen. When using the 
RexxUtil functions, you do not need to use “ECHO OFF” prevent the 
command echo. 


¢ The RexxUtil functions can be faster than the OS/2 operating system command. 


Figure 12-2 shows a program called INSTALL.CMD. That program uses the 
RexxUtil SysMkDir and SysFileDelete functions to install an application. 


/* Application install program - Install information */ 
/* comes from an application control file dl | 
parse arg product /* get product name 


call setup /* read control info * 
rc = SysMkDir directory /* create main directory*/ 
if rc <> 0 then do /* already installed */ 
say product 'is already installed. Do you wish to’ 
say product ‘continue? (Yes/No) ' 
pull answer 
if answer <> 'YES' then exit 100 
/* delete old files ¥) 
do i = 1 to files.0 
call SysDeleteFile 'C:'files.i 
end 
end 
/* get free space *} 
parse value SysDriveInfo('C:') with . free . 
/* not enough room */ 
if free < required_space then do 
say ‘Product’ product ‘requires’ required_space 
say ‘bytes of storage. You only have' free ‘bytes’ 
say ‘available. Please make more space available on' 
say 'the drive and try again.' 
exit 100 
end 


do i = 1 to directories /* make subdirectories */ 
call SysMkDir directories.i 
end 


do i = 1 to files /* copy the files *] 
say ‘Copying C:'files.i 
'@copy A:'files.i 'C:'files.i '> NUL' 

end 


Figure 12-2 (Part 1 of 2). INSTALL.CMD 
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Setup: 


file = product||'.CTL' 
files = 0 

directories = 0 

call on notready 

eof = 0 


line = linein(file) 

do while \eof 
parse var line type value 
select 


read control file 

read control information 
no files to read 

no subdirectories 

set up end-of-file handler 
not at end yet 


get first line 

read entire file 

get the first word 
process the record type 


product root directory 
when type = 'DIRECTORY' then 
directory = value 
/* product subdirectories 
when type = 'SUBDIRECTORY' then do 
directories = directories + 1 
directories.directories = value 
end 
/* product files (with the 
/* target directories 
when type = 'FILE' then do 
files = files + 1 
files.files = value 
_ end 
otherwise nop 
end 
line = linein(file) 
end 
return 


get next line 


Figure 12-2 (Part 2 of 2). INSTALL.CMD 


Functions for Saving Information 
You can use use the RexxUtil SysPutEA, SysGetEA, and SysIni functions to save 
information outside of your REXX programs: 


SysPutEA 
Saves information in a file’s extended attributes. SysPutEA stores the 
information as a named attribute. The SysGetEA retrieves the saved 
information using the name you used with SysPutEA. The extended attributes 
remain with the file until the file is erased. . 


SysGetEA 
Retrieves information from a file’s extended attributes. The extended attribute 
may have been stored by the SysPutEA function or another program. 


SysIni 
Saves and retrieves information from a system profile file. Profile information 
is stored as Application Names with associated Key Names. You can store 
information in the system profile (OS2SYS.INI), the user profile (OS2.INI), or 
any profile file you designate. 


Information you save with SysPutEA remains with the named file as hidden 
information. It not visible when you edit or type the file, but you can retrieve it 
using the SysGetEA function. Information you save with the SysIni function is 
written to an OS/2 operating system profile file. You save the information under an 
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application name and a key name. For example, a text editor might store profile 
information using an “Editor” application name with application keys of 
“TempFile,” “Dictionary,” and “DefaultOptions.” 


Figure 12-3 and Figure 12-4 show how compiler option information is saved in a 
file’s extended attributes and in a PROJECT.INI profile file. The DOCOMP.CMD 
program uses the information stored in the extended attributes and the 
PROJECT.INI file to compile a source file. 


/* Store file compilation options in extended attributes 
parse arg file options /* get the file name and options 


/* set the compile options 
call SysPutEA file, 'Compile_options', options 


Figure 12-3. SETCOMP.CMD 


/* Store project file compilation options in profile 
parse arg options /* get the options 

/* find the profile 
profile = SysSearchPath('DPATH', 'PROFILE.INI') 


if profile = '' then /* find it? 
profile = 'PROFILE.INI' /* place in current directory 
/* set the compile options 
call SysIni profile, 'Compiler', 'Options', options 


Figure 12-4. SETPROJ.CMD 
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—* 


Using the Screen 


/* Compile a program using the options stored in the program 
/* source extended attributes 
parse arg file /* get the file name 

/* retrieve the file options 
rc = SysGetEA file, 'Compile_options', ‘options’ 


if rc <> @ then do /* no options for file? 
/* find the profile 
profile = SysSearchPath('DPATH', 'PROFILE.INI') 
if profile <> '' then /* find it? 
/* retrieve default options 
options = SysIni(project, ‘Compiler', 'Options') 
end 


'CC' options file /* compile it 


Figure 12-5. DOCOMP.CMD 


When you run a REXX program in an OS/2 windowed session or an OS/2 full 
screen session, you can control the screen with the RexxUtil text screen functions. 
The text screen functions are: 


SysCurPos 
Places the cursor at a screen row and column position. You can also use 
SysCurPos to obtain the current cursor position. 


SysCurState 
Hides the cursor or makes the cursor visible. 


SysGetKey 
Reads the next key from the keyboard buffer. If the keyboard buffer is empty, 
SysGetKey will wait until a key is pressed. 


SysTextScreenRead 
Reads characters from the screen. 


SysTextScreenSize 
Returns the screen size. 


You cannot use the text screen functions in REXX programs running under 
PMREXxX or called from a Presentation Manager application. 


You can use the text screen functions for screen input and output functions not 
possible with the REXX input and output built-in functions. For example, 
Figure 12-6 contains a REXX program that reads a password from the screen 
without revealing the characters typed. 
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/* Read a password from the screen */ 

Valid = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890#$@' 
Passwd = '' 

MaxLength = 8 


ETK = d2c(13) /* Enter key 
/* Backspace 
/* Extended key 
/* Extended key 


do forever /* Loop until complete 
Ch = translate(SysGetKey('NOECHO')) 
select 
when Ch = ETK /* Enter key pressed 
then do 
say '' /* Give a carriage return 
leave 
end 
when Ch = BS /* Backspace 
then if PassWd = '' 
then call Beep 262, 200 


else do /* Overstrike a blank 
call charout ,BS BS 
PassWd = left(PassWd, length(PassWd)-1) 
end 
/* All other characters 
when pos(Ch, Valid) > 0 
then if length(PassWd) = MaxLength 
then call Beep 262, 200 
else do 
call charout ,'*' 
Passwd = PassWd||Ch 
end 
otherwise do /* Swallow next for extended*/ 
if Ch = X1 [ Ch = X2 
then call SysGetKey('NOECHO') 
call beep 262, 200 
end 
end 
end 
return PassWd 


Figure 12-6. GETPASS.CMD 


GETPASS.CMD uses the SysGetKey function to read characters from the keyboard. 
SysGetKey reads each character as you type it and does not echo the character to 
the screen. 


When SysGetKey is combined with the other RexxUtil text screen functions, you can 


create text based menu systems. Figure 12-7 on page 12-9 contains an example of a 
simple menu program. 
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NU 


/* Place a simple menu on the screen 

** These functions are used to create the following subroutines: 

kk 

** ~~ MakeWindow Reserves part of a window as a sub-window. 

+ Draws a border and returns a window handle. 

**  WriteWindow - Writes a line into a sub-window 

** ~ WriteMenu Write a menu-line into a window, where accelerator 
baad keys are underlined 

*x WaitMenu Waits until one of the menu entries are selected, 
bias and returns the choice. 

af 

handles = 0 

Call SysCls 


handle = Makewindow(5,5,10,50) 

call writewindow handle, 5 ,10, ‘This is a demo.' 

call writewindow handle, 7 ,10, ‘Choose an item from the Menu above.' 
call writemenu handle, ‘Quit “Exit Lea’ve' 

call Waitmenu handle 

Call writeWindow handle, 9, 5, ‘You entered' result 

call syscurpos 23,0 

exit 


[RERERIIEERREAE ER EER EREREREAARERNAAE ERR SER ESE S REX EELESERERESL NAR AEREN | 


This routine reserves a portion of the text window as a 


* 
sub-window. The window is defined by giving the position of its */ 
upper left hand corner (based on 0,0 being the upper left hand */ 
corner of the text window), and the size in rows and columns. 


The sub-window is blanked out and a border is drawn around it. 
This routine assigns a window handle to the window. That handle 
is passed to the other routines to identify which window they 
should act on. 


Return values: negative number if there is an error. 
a positive number is a valid window handle. 
HERERERREEERERRREERERE IHREN REE EARNER ER RIAA RIERA TAIRA IIIT ERE | 
MakeWindow: Procedure expose handles Windowdata. 
Arg orgrow, orgcol, rows, cols 


/* First make sure the requested sub-window will fit ay 
Parse Value SysTextScreenSize() With ssrows sscols 
Select 

When orgrow < 0 Then Return -1 

When orgcol < 0 Then Return -2 

When rows < 0 Then Return -3 

When cols < @ Then Return -4 

When orgrow + rows > ssrows Then Return -5 

When orgrow + rows > ssrows Then Return -6 

Otherwise Nop /* No error on input */ 
End 


Figure 12-7 (Part 1 of 4). TEXTMENU.CMD 
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/* Record data about window for future use. 
handles = handles + 1 
WindowData.handles._orgrow = orgrow 
WindowData.handles. orgcol = orgcol 
WindowData.handles._rows = rows 
WindowData.handles._cols = cols 


/* Now draw the window 
FillerLine = copies('t',cols -2) 
BlankLine = copies(' ',cols -2) 


Call WriteLineAbsolute orgrow, orgcol, ‘e'fillerline''' 
Do ii = orgrow + 1 for rows -1 

Call WriteLineAbsolute ii, orgcol, '%'blankline'%' 
End 
Call WriteLineAbsolute ii, orgcol, '2'fillerline''' 


Return handles 


ERREEREERERERRERRERREERREREERERER AAR ERA EERE RRR RRERR RARE RERER ERENT | 


/* This routine will write one line of text into a sub-window. od | 
/* The caller specifies the row and column number to place the text.*/ 
/* This location is based on the upper left hand corner of the ay 
/* sub-window, which is defined as 1,1. - 
/* Text is not allowed to overlay the window border. */ 
REELEASA EERE SERA EEN ET ENA A ERED NEREAEE SEE ES? RESERV ERR IANS SENECA E NS 
WriteWindow: Procedure expose handles Windowdata. 
Parse Arg Handle, row, col, text 


/* Make sure the window handle is OK, and the text will fit in the */ 
/* window. . 
Select 

When handle < 0 Then Return -1 

When handle > handles Then Return -2 

When row <=1 Then Return -3 

When col <=1 Then Return -4 

When row >= Windowdata.handle._rows Then return -5— 

When length(text) + col > Windowdata.handle. cols Then return -6 

Otherwise Nop 
End 


/* Calculate the location and write the text 
AbsoluteRow = Windowdata.handle._orgrow + row 
AbsoluteCol = Windowdata.handle._orgcol + col 

Call WriteLineAbsolute AbsoluteRow, AbsoluteCol, text 
Return 0 


Figure 12-7 (Part 2 of 4). TEXTMENU.CMD 
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Jf EREIREAS RAREST EN EET A REEEERN TEN SO SE ON AG TORN RS ee Tee eee ey ee Tart 


/* This routine takes a string of words and writes it on the top of */ 
/* a window as a menu. Each word should have a ~ character in */ 
front of the character which will be used to select it. 
Each of these characters will be underlined and written as a 
capital letter. The caller must ensure that no duplicate 
selection characters are included in the word list. 
HHKKERERERERERIR ARIA IERIE KEIR IAAI AR IAAI AAAI IA IRISH THRE | 
WriteMenu: Procedure expose handles Windowdata. 
Parse Arg handle, orgtext 


/* We make the input text all lower case, the uppercase the 
/* selection characters later. 
orgtext = Translate(orgtext, xrange('a','z'), erangel’ A', 'Z')) 


MenuText = '' /* output word list 

UnderlineText = '' /* output underline characters */ 
MenuCount = 0 /* how many selections so far af 
JustDidUnderline = 0 /* did we just find a ~ character?*/ 


Do OrgCounter = 1 to length(orgtext) 
OrgChar = substr(OrgText, OrgCounter, 1) 


if Orgchar <> '~' Then Do 
If JustDidUnderline Then Do /* put in uppercase letter 
MenuText = MenuText || translate(OrgChar) 
JustDidUnderline = 0 
MenuCount = MenuCount + 1 


/* remember the accelerator keys for use by WaitMenu routine 
WindowData.handle._Accelkey.MenuCount = Translate(OrgChar) 
End 
Else Do /* put in lower case letter 
UnderlineText = UnderlineText || ' ' 
MenuText = MenuText || OrgChar 
End 
End 
Else Do /* found a ~ character 
UnderlineText = UnderlineText || 't' 
JustDidUnderline = 1 
End 
End Orgcounter 


Windowdata.handle. MenuCount = MenuCount 


/* Now we have the menu text. Write to the top of the window, 
/* center, with the underline row below it. 

width = Windowdata.handle._cols - 3 

Call WriteWindow handle, 2, 2, center(MenuText, width) 

if result < 0 then Return result 

Call WriteWindow handle, 3, 2, center(UnderlineText, width) 
Return result 


Figure 12-7 (Part 3 of 4). TEXTMENU.CMD 
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PEASE REE NS MELEE ES EESEEAR SSE CN SARA MASSA SALAS ES TRS OT AA TRAE ER ONE ASN AAS | 


/* This is a simple routine that writes a line of text to a location*/ 


/* defined in relation to the main text window. */ 
[EERO E ESTE EERE RETR ER SEER EERE REREEREEERRERERERER EN SERKERES ER EER 


WriteLineAbsolute: Procedure 
Parse Arg row, col, text 
Call SysCurPos row, col 

call charout , text 

Return 


MALRENERA ENS SESE LE UAEEERASARALER SEU NE RAE RERER SSE EAD REA EER ERE R ONES 


/* This routine waits for the user to select a menu choice by */ 
/* pressing a key that corresponds to one of the selection * 
/* characters defined for a given window. */ 
/* Any other keys are ignored. +7. 
LEREREE AER EINS REAEE AS RARE ERASLES A RNAEE ERED PERERA SARE SAERALERER ES NEES 7 
WaitMenu: Procedure expose handles Windowdata. 

arg handle 


/* Make sure the window handle is OK. */ 
Select 

When Handle < 0 Then Return -1 

When handle > handles Then Return -2 

Otherwise Nop 
End 


/* Turn off cursor and wait for an expected character 
Call syscurstate 'OFF' 
Do outerloop = 0 
char = translate(SysGetKey('NOECHO')) 
do ii = 1 to Windowdata.handie. MenuCount 
if char = Windowdata.handle._accelkey.ii Then Leave outerloop 
End 
End outerloop 


/* Turn cursor back on and return uppercase of the selection char. 
Call syscurstate 'OFF' 
return char 


Figure 12-7 (Part 4 of 4). TEXTMENU.CMD 


When you run TEXTMENU.CMD, a small menu box appears on the screen. 


Quit Exit leaVe 


This is a demo. 


Choose an item from the Menu above. 


Figure 12-8. TEXTMENU.CMD Display 


When you press a Q, E, or V key, the menu displays your selection and the program 
ends. 
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Seaching Functions 


Rexx Util also includes some functions for searching files and directories. The 
program FINDFILE.CMD in Figure 12-9 creates a list of files that matches a file 
specification containing a given character string. FINDFILE.CMD uses the 
RexxUtil SysFileTree, SysFileSearch, and SysDriveMap functions. 


/* Search all drives for files with a given string */ 
parse arg filespec '"' string '"' 


drivelist = SysDriveMap() /* get list of drives uA 


do while drivelist <> '' /* check each drive af 
parse var drivelist drive drivelist 

/* get the list of matching*/ 

/* files on this drive *] 


do i = 1 to files.0 /* seach each file 
call SysFileSearch string, files.i, ‘Lines.', ‘NC' 


if lines.@ > @ then do /* found something, = 
say '===> "'string'"' found in file' files.i' 
do j = 1 to lines.0 

say ' ‘ lines.j 

end 

end 

end 
end 


Figure 12-9. FINDFILE.CMD 


The SysFileTree and SysFileSearch functions are different from the functions you’ve 
already tried. SysFileTree and SysFileSearch return lists of information by placing 
them directly into an array of REXX compound variables. The compound variables 
begin with a stem name that you provide to the SysFileTree or SysFileSearch 
functions. For example, the following SysFileTree calls returns a list of file names 
using the FILES. stem variable: 


call SysFileTree drive'\', 'Files.', 'sf' 


SysFileTree returns the list size in compound variable FILES.0. Variables FILES.1, 
FILES.2, up to the size contained in FILES.0 contains the members of the list. 


Additional RexxUtil Functions 


Rexx Util contains many more functions than are covered here. There are functions 
for creating objects and object classes, functions for obtaining system values, and 
even a function to put your REXX program to sleep. 


For a more complete discussion of REXX utilities, refer to “Rexx Utilities” in the 
REXX Reference. 
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equal operator 4-10, 4-15, 9-17 differences with subroutines 7-13 
ERROR condition 5-15, 7-15 . DIGITS 9-16 
error conditions external 7-13 
ERROR 5-15, 7-15 FORMAT() 9-9 
FAILURE 5-15, 7-16 FUZZ 9-17 
NOTREADY 7-16 internal 7-13 
NOVALUE 7-16 LENGTH 4-12 
SYNTAX 7-16 — . search order 7-13 
error 13 4-3 similarities with subroutines 7-13 
evaluating expressions SUBSTR 4-12 
order of 4-10 SYMBOL 3-16 
using parentheses 4-11 TRUNC 9-7 
evaluation priority 4-10, 4-11 functions, commands replaced by 12-3 
exact comparison operators 4-10, 4-15, 9-17 function, register a 12-3 
exactly equal operator 4-10, 4-15, 9-17 FUZZ 9-17 
exclusive OR operator 4-10 FUZZ option of NUMERIC instruction 9-17 


exponent 9-5 fuzzy arithmetical comparison 9-17 
exponential notation - 

description of ‘9-1, 9-5 

NUMERIC DIGITS instruction 9-16 
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G 


get extended attributes 12-5 

getting command-line data 8-4 

getting data when you are prompted 8-2 
greater than operator 4-5, 4-10 

greater than or equal to operator 4-10 


H 


hexadecimal 
converting 4-20 
description of 4-19 


IF instruction 

description of 6-2 

ELSE keyword 6-5 

THEN keyword 6-2 
increasing accuracy in calculations 9-16 
input and output 10-1 

default input/output streams 10-15 

input and output 10-1 
instructions 

CALL 5-14, 7-2 

DO 6-1 

DO FOREVER 6-13 

DO UNTIL 6-15 

DO WHILE 6-14 

EXIT 6-23 

ITERATE 6-30 

LEAVE 6-13 

NOP 6-29 

NUMERIC DIGITS 9-16 

NUMERIC FUZZ 9-17 

PARSE ARG 8-5 

PARSE PULL 8-2 

PARSE VALUE 8-9 

PARSE VAR 8-9 

PROCEDURE 3-16 

PULL 8-2 

QUEUE 10-i1 

SAY 8-1 

SELECT 6-7 

SIGNAL 5-14, 7-14 

TRACE 4-7 
integer 9-1 — 
integer division operator 4-10, 9-3 
internal routines 

functions 7-13 

subroutines 3-17, 7-7, 7-13 
interpreter 1-1 
invalid character in program 4-3 
issuing commands 

evaluation rules 5-6 

to application environments 5-14 

using ADDRESS 5-7 


ITERATE instruction 6-30 


J 


jumping through your program 6-30, 7-14 


K 
keyboard input (STDIN) 10-15 
keywords 
of DO instruction 
of IF instruction 
ELSE 6-5 
THEN 6-2 
of SELECT instruction 
END 6-7 
OTHERWISE 6-7 
THEN 6-7 
WHEN 6-7 


L 
label 7-2, 7-8 
LEAVE instruction 6-12, 6-33 
leaving loops 6-33 
LENGTH function 4-12 
less than operator 4-5, 4-10 
less than or equal to operator 4-10 
literal patterns in parsing 8-10 
load a RexxUtil function 12-3 
loops 
conditional 6-13 
control variable 6-20 
counter 6-33 
DO FOREVER instruction 6-13, 6-17 
DO UNTIL instruction 6-15, 6-16 
DO WHILE instruction 6-14, 6-16 
ITERATE instruction 6-30 
LEAVE instruction 6-13, 6-33 
leaving 6-33 
repetitive 6-11 
skipping instructions 6-30, 7-14 


macros 5-1 
macros, environments for 5-14 
mantissa 9-5 
messages 
from OS/2 to REXX 5-9 
suppressing 
minus operator 4-10, 9-3 
multiple clauses on a line 2-10 
multiplication 9-3 
multiplication operator 4-10, 9-3 


Index 


N patterns used in parsing 8-10 
period 
as a placeholder in parsing 8-7 
in compound symbols 3-8 


naming variables 3-3 
NOP instruction 6-29 


not equal operator 4-10, 4-15, 9-17 placeholder, period, in parsing 8-7 
not exactly equal operator 4-10, 4-15, 9-17 plus operator 4-10, 9-3 

not greater than operator 4-10 PMREXX 5-17 

not less than operator 4-10 starting 5-17 

NOTREADY condition 7-16 tracing 5-19 

NOVALUE condition 7-16 power of a number 9-3, 9-17 
numbers 


precedence 
of characters 4-14 
operators 4-10 
priority of characters 4-14 
priority of operators 4-10 


comparing 4-13 
exponential notation 9-5 
fixed-point 9-5 
floating-point 9-5 


power of 9-3, 9-17 PROCEDURE instruction 
range of 9-5 description of 3-16 
ports ee EXPOSE keyword 3-16 
runcating 9- 

programs 
ete a correcting 11-8 
whole 9-1 


description of 6-1 
designing 11-4 
prompting user for data 8-2 
PULL instruction 
O description of 8-2 
using 2-2, 8-5 


NUMERIC DIGITS instruction 9-16 
NUMERIC FUZZ instruction 9-17 


operator : i ; 
comparison 4-5, 4-10, 4-13 putting words into variables 8-5 
list of 4-10 
priority of 4-10 Q 


using parentheses 4-11 
OR operator 4-17 
OS/2 publications ix 
_ OS/2 (operating system) 
as REXX environment 5-1 
batch (CMD) files in 5-13 
issuing commands to 5-1 
REXX error handling (with RC) 5-9 
OTHERWISE keyword 6-7 


queue described 10-11 
quotation marks 

in literal strings 2-5 

to avoid conflicts with OS/2 conventions 5-5 
quotes 

in literal strings 2-5 

to avoid conflicts with OS/2 conventions 5-5 


output format 9-9 R 
range of numbers 9-5 
p RC variable 3-15, 5-9 


read and write positions 10-20 
register a function 12-3 : 
remainder 9-3 


parentheses 4-11 

PARSE ARG instruction 8-5 
PARSE PULL instruction 8-2 remainder operator 4-10, 9-3 
PARSE VALUE instruction 8-9 repetitive loops 6-11 


PARSE VAR instruction 8-9 RESULT reserved symbol 7-3 
parsing retrieve extended attributes 12-5 
arguments 7-5, 8-4 return codes 
data when you are prompted 8-2 reading and responding to 5-9 
expressions 8-9 REXX 2-7 
use of a period 8-7 returning from a subroutine 7-3 
using literal patterns 8-10 REXX programs, REXXTRY 5-10 
using patterns 8-10 — REXXTRY, using 5-10 
variables 8-9 RexxUtil functions 12-3 
words 8-5 commands replaced by 12-3 
RxFuncAdd 12-3 
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RexxUtil functions (continued) 
SysCls 12-3 
SysCurPos 12-7 
SysCurState 12-7 
SysFileDelete 12-3 
SysGetKey 12-7 
SysIni 12-5 
SysLoadFuncs 12-3 
SysMkDir 12-3 
SysPutEa 12-5 
SysTextScreenRead 12-7 
SysTextScreenSize 12-7 
RexxUtil functions, availability of 12-3 
rounding numbers 9-7 
RxFuncAdd 12-3 


S 
SAA_ 1-2 
save extended attributes 12-5 
search order for subroutines and functions 7-13 
SELECT instruction 

description of 6-7 

END keyword 6-7 

example of 6-9 

OTHERWISE keyword 6-7 

THEN keyword 6-7 

WHEN keyword 6-7 
separating clauses 2-10 
SIGL variable 

storing line numbers 7-15 
SIGNAL instruction 

description of 7-14 

restrictions 7-14 - 

used injumps 7-14 

used to trap command errors 5-14 
signed number 9-1 
significant digits 9-16 
skipping instructions in a loop 6-30, 7-14 
special variables 3-15 
splitting 

clauses 2-10 

data 8-5 
starting PMREXX 5-17 
STDIN (default input stream) 10-15 
STDOUT (default output stream) 10-15 
stem 

description of 3-13 

example of 3-13 
streams 10-1 
STREAMO function 10-18 

strictly greater than operator 4-10 

strictly greater than or equal to operator 4-10 
strictly less than operator 4-10 
strictly less than or equal to operator 4-10 
strictly not greater than operator 4-10 
strictly not less operator 4-10 


string 
description of 2-5 
examples of 2-5 
finding the length 4-12 
getting a substring 4-12 
subcommand processing 5-14 
subroutines 
arguments for 7-2 
description of 7-1 
differences with functions 7-13 
example of 3-17 
external 7-4, 7-13 
internal 3-17, 7-7, 7-13 
PROCEDURE instruction 3-16 
protecting variables 3-16 
RETURN instruction 7-3 
search order 7-13 
sharing variables 3-17 
similarities with functions 7-13 
SUBSTR function 4-12 
substring 4-12 
subtraction 9-3 
subtraction operator 4-10, 9-3 
symbol 
compound 3-8 
determining if it is a variable 3-16 
SYMBOL function 3-16 
SYNTAX condition 7-16 
syntax error 
example of 2-7 
FORMATO function 9-9 
syntax, description of 2-6 
SysCls 12-3 
SysCurPos 12-7 
SysCurState 12-7 
SysFileDelete 12-3 
SysGetKey 12-7 
SysIni 12-5 
SysLoadFuncs 12-3 
SysMkDir 12-3 
SysPutEA 12-5 
SysRmDir 12-3 
system messages 5-9 
Systems Application Architecture 1-2 
SysTextScreenRead 12-7 
SysTextScreenSize 12-7 


T 


THEN keyword 
NOP instruction 6-29 
of IF instruction 6-2 
of SELECT instruction 6-7 
TRACE 
intermediate results 4-7 
results 4-7, 4-9 
TRACE flags 
+++ 11-10 “a 


Index 
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TRACE flags (continued) 


*-* 11-10 
>C> 11-10 
>F> 11-10 
>L> 11-10 
>O> 11-10 
>P> 11-10 
>V>_ 11-10 
>.> 11-10 
>>> 11-10 


trace function in PMREXX 5-19 
TRACE instruction 4-7 
tracing 

description of 4-7 

example 4-7 
translating 


between character, hexadecimal, decimal 4-20 


examples of 4-20 

to uppercase 2-6 
trapping command errors 5-14 
TRUE expression 4-6 
TRUNC function 9-7 
truncating numbers 9-7 


U 


uppercase translation 2-6 


V 


variables 
built-in 3-15, 5-9 
incommands 5-4 
length of 4-12 
names and OS/2 conventions 5-5 
naming conventions 3-3 
parsing 8-9 
protecting 3-16 
setting of 8-5 
sharing between routines 3-17 


W 

WHEN keyword 6-7 

whole numbers 9-1 

word, parsing 8-5 

write and read positions 10-20 
writing lines to the screen 8-1 


Special Characters 

. (as a placeholder) 8-7 

. (in compound symbols) 3-8 

< (less than operator) 4-5, 4-10 

<< (strictly less than operator) 4-10 


<<= (strictly less than or equal to operator) 4-10 
<= (less than or equal to operator) 4-10 
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+ (addition operator) 4-10, 9-3 
+++ tracing flag 11-10 
&& (exclusive OR operator) 4-10 
& (AND operator) 4-17 
* (multiplication operator) 9-3 
*-* tracing flag 11-10 
** (exponentiation operator) 4-10, 9-3, 9-17 
*/ comment delimiter 2-4 
/ (division operator) 4-10, 9-3 
/* comment delimiter 2-4 
// (remainder operator) 4-10, 9-3 
% (integer division operator) 4-10, 9-3 
> (greater than operator) 4-5, 4-10 
>C> tracing flag 11-10 
>F> tracing flag 11-10 
>L> tracing flag 11-10 
>O> tracing flag 11-10 
>P> tracing flag 11-10 
>V> tracing flag 11-10 
>.> tracing flag 11-10 
>> (strictly greater than operator) 4-10 
>>> tracing flag 11-10 
>>= (strictly greater than or equal to operator) 4-10 
>= (greater than or equal to operator) 4-10 
= (equal operator) 4-5, 4-10, 4-15, 9-17 
== (exactly equal operator) 4-10, 4-15, 9-17 
— (subtraction operator) 4-10 
\< (not less than operator) 4-10 
\<< (strictly not less than operator) 4-10 
\> (not greater than operator) 4-10 
\>> (strictly not greater than operator) 4-10 
\= (not equal operator) 4-10, 4-15, 9-17 
== (not exactly equal operator) 4-10, 4-15, 9-17 
11 (concatenation operator) 4-3, 4-10 
| (inclusive OR operator) 4-17 
|| (concatenation operator) 4-3 
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